@webhands/core 0.1.0

package/src/remote-session.ts

@@ -0,0 +1,66 @@
+import {
+	makeRpcPage,
+	SESSION_RPC_PATH,
+	type SessionRpcRequest,
+	type SessionRpcResponse,
+} from './session-rpc.js';
+import type {Session} from './seam.js';
+
+/**
+ * A client-side {@link Session} that drives a session living in a SEPARATE
+ * long-lived `serve` process over HTTP (ADR-0005).
+ *
+ * Each `webhands <verb>` is a thin client: it cannot hold a JS
+ * reference to the server's live page, so this proxy turns every {@link Page}
+ * verb into a session-RPC call to the running server (see `session-rpc.ts`) and
+ * returns the result. The verb command code is UNCHANGED — it still calls
+ * `provider(target)` then runs verbs against the returned `Session.page` then
+ * calls `Session.close()`; only WHAT the session is changes.
+ *
+ * The critical difference from a local session: {@link Session.close} here is a
+ * NO-OP. The served process owns the single live session's lifetime; a thin
+ * client closing after one verb must NOT tear down the shared browser, or the
+ * next verb invocation would have nothing to drive. Teardown is explicit
+ * (`stop`), exactly as ADR-0005 requires. This is the whole reason cross-
+ * invocation persistence works: the page state survives because the client's
+ * `close()` does not reach across to the server's session.
+ */
+export function connectRemoteSession(baseUrl: string): Session {
+	const endpoint = new URL(SESSION_RPC_PATH, baseUrl).toString();
+
+	const send = async (request: SessionRpcRequest): Promise<unknown> => {
+		let res: Response;
+		try {
+			res = await fetch(endpoint, {
+				method: 'POST',
+				headers: {'content-type': 'application/json'},
+				body: JSON.stringify(request),
+			});
+		} catch (cause) {
+			// The advertised server is unreachable (it died without clearing its
+			// endpoint file, say). Surface a plain Error; the CLI maps the discovery
+			// MISS (no endpoint file) to "run serve first", but a stale-but-present
+			// endpoint that no longer answers is a genuine connection failure.
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new Error(
+				`could not reach the session server at ${baseUrl}: ${message}`,
+			);
+		}
+		const reply = (await res.json()) as SessionRpcResponse;
+		if (reply.ok) {
+			return reply.value;
+		}
+		// Re-throw a faithful Error so a page-side throw REJECTS on the client too,
+		// preserving the seam's `eval` "a page throw rejects" contract across the
+		// process boundary.
+		throw new Error(reply.error);
+	};
+
+	return {
+		page: makeRpcPage(send),
+		async close() {
+			// Intentionally a no-op: the served process owns the session's lifetime
+			// (see this module's overview). Teardown is the explicit `stop` verb.
+		},
+	};
+}

package/src/seam.ts

@@ -0,0 +1,222 @@
+/**
+ * The verb-level transport seam.
+ *
+ * This is the highest test seam and the internal structure boundary of
+ * `core` (see PRD "Testing Decisions" and `docs/adr/0003`). It is expressed
+ * purely in terms of high-level VERBS (navigate, snapshot, click, type, eval,
+ * wait, cookies), NOT in terms of CDP or Playwright primitives, so that a
+ * future browser-extension transport or a non-Chromium (Firefox) transport
+ * can implement it without changing the verb surface.
+ *
+ * RULES (load-bearing, do not relax without an ADR):
+ * - No CDP / Chromium-only types may appear in this public surface
+ *   (`docs/adr/0003`).
+ * - Element addressing is a RAW PLAYWRIGHT LOCATOR STRING the active
+ *   transport resolves (`docs/adr/0004`): "transport-neutral" means
+ *   Playwright-equivalent addressing, not a reduced selector subset and not a
+ *   structured JSON locator. We deliberately type it as a branded `string`
+ *   rather than importing any Playwright `Locator` type, so no Playwright
+ *   type leaks across the seam.
+ */
+
+/**
+ * A raw Playwright locator string, e.g. `getByRole('button', { name: 'Search' })`.
+ *
+ * It is a plain `string` at runtime; the brand exists only so call sites are
+ * explicit that this is a locator EXPRESSION the transport resolves (a sibling
+ * to the `eval` escape hatch), not an opaque CSS selector or a structured
+ * locator. Construct one with {@link locator}.
+ */
+export type LocatorString = string & {
+	readonly __brand: 'PlaywrightLocatorString';
+};
+
+/** Tag a raw Playwright locator string as a {@link LocatorString}. */
+export function locator(expression: string): LocatorString {
+	return expression as LocatorString;
+}
+
+/**
+ * How a {@link Transport} should obtain a browser session.
+ *
+ * Expressed in domain terms (a profile to launch, or a target to attach to),
+ * never in CDP/Playwright terms. Concrete transports map these to their own
+ * mechanism (Playwright `launchPersistentContext` / `connectOverCDP`, an
+ * extension bridge, ...).
+ */
+export type OpenTarget =
+	| {
+			readonly mode: 'launch';
+			/** Name of the dedicated profile the controller owns. */
+			readonly profile: string;
+			/** Whether the browser is visible. Defaults are a transport concern. */
+			readonly headed?: boolean;
+	  }
+	| {
+			readonly mode: 'attach';
+			/**
+			 * Opaque, transport-resolved endpoint of an already-running browser
+			 * (e.g. a remote-debugging URL). Kept as a plain string so no
+			 * CDP type leaks across the seam.
+			 */
+			readonly endpoint: string;
+	  };
+
+/** A single browser cookie, in transport-neutral terms. */
+export interface Cookie {
+	readonly name: string;
+	readonly value: string;
+	readonly domain?: string;
+	readonly path?: string;
+	readonly expires?: number;
+	readonly httpOnly?: boolean;
+	readonly secure?: boolean;
+	readonly sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+/** What to wait for in the {@link Page.wait} verb. */
+export type WaitCondition =
+	| {readonly kind: 'timeout'; readonly ms: number}
+	| {readonly kind: 'locator'; readonly target: LocatorString}
+	| {readonly kind: 'navigation'};
+
+/**
+ * Which page view a {@link Snapshot} carries.
+ *
+ * - `'accessibility'` — the DEFAULT, token-cheap structured view: the
+ *   accessibility tree (roles + names) plus visible text, with stable element
+ *   refs (see {@link Snapshot.content}). This is the cheap view an agent reads
+ *   to decide what to act on WITHOUT parsing raw HTML.
+ * - `'full'` — the raw DOM (serialized outer HTML), returned when the verb is
+ *   called with {@link SnapshotOptions.full}. A settled PRD decision (story 7,
+ *   `needsAnswers` Q3): default is the accessibility view, `--full` is raw DOM.
+ */
+export type SnapshotView = 'accessibility' | 'full';
+
+/** Options for the {@link Page.snapshot} verb. */
+export interface SnapshotOptions {
+	/**
+	 * When `true`, return the raw DOM (`view: 'full'`) instead of the default
+	 * accessibility-tree + visible-text view. Maps to the CLI `--full` flag.
+	 */
+	readonly full?: boolean;
+}
+
+/**
+ * A structured, token-cheap view of the current page with stable element refs.
+ *
+ * In the default `'accessibility'` view, {@link Snapshot.content} is the
+ * accessibility tree (roles + accessible names) plus visible text, with each
+ * actionable node carrying a stable `[ref=...]` element reference. The refs
+ * are stable for an unchanged page (re-snapshotting yields the same refs), so
+ * an agent can read the cheap view, pick a ref, and address that element
+ * later. Snapshot refs and the raw Playwright-locator addressing (ADR-0004)
+ * are COMPLEMENTARY ways to address elements, not competitors.
+ *
+ * The `content` string is a transport-neutral, human/agent-readable text
+ * serialization (no CDP/Playwright types cross the seam, per ADR-0003). Its
+ * concrete grammar is a transport detail; callers treat it as opaque,
+ * token-cheap text to read, and parse refs out of it only by the documented
+ * `[ref=...]` convention.
+ */
+export interface Snapshot {
+	/** The page URL at snapshot time. */
+	readonly url: string;
+	/** Which view this snapshot carries (default vs `--full` raw DOM). */
+	readonly view: SnapshotView;
+	/** Human/agent-readable structured page content (see {@link Snapshot}). */
+	readonly content: string;
+}
+
+/**
+ * The page-level verb surface. One method per verb in the domain glossary.
+ * All element addressing flows through {@link LocatorString}.
+ */
+export interface Page {
+	/** Navigate the active page to a URL and let it settle. */
+	navigate(url: string): Promise<void>;
+	/**
+	 * Return a structured, token-cheap view of the page. Defaults to the
+	 * accessibility-tree + visible-text view with stable refs; pass
+	 * `{full: true}` to get the raw DOM instead (PRD story 7).
+	 */
+	snapshot(options?: SnapshotOptions): Promise<Snapshot>;
+	/** Click the element addressed by a raw Playwright locator string. */
+	click(target: LocatorString): Promise<void>;
+	/** Type text into the element addressed by a raw Playwright locator string. */
+	type(target: LocatorString, text: string): Promise<void>;
+	/**
+	 * Run a JavaScript EXPRESSION in the active page's context and return its
+	 * result, the `eval` escape hatch for cases no other verb covers (PRD story
+	 * 9). It sits naturally beside the raw-locator addressing (ADR-0004): both are
+	 * page-context expressions the transport resolves.
+	 *
+	 * `expression` is evaluated AS AN EXPRESSION (not a function body), so its
+	 * value is the result: `'1 + 2'` yields `3`, `"document.title"` yields the
+	 * title. If it evaluates to a Promise, the transport awaits it and returns the
+	 * resolved value.
+	 *
+	 * SERIALIZATION CONTRACT (the load-bearing part). The result must cross the
+	 * seam by VALUE: it is structurally cloned out of the page context, not
+	 * handed back as a live reference. The transport, not this verb, owns the
+	 * serialization, and its behaviour is the documented contract callers rely
+	 * on. It is RICHER than `JSON.stringify` (do not reason about it as JSON):
+	 * - Primitives, plain objects, and arrays round-trip faithfully, including
+	 *   nested structures.
+	 * - `undefined` round-trips as `undefined`; `null` as `null`.
+	 * - Non-finite numbers (`NaN`, `Infinity`, `-0`) and `BigInt` are PRESERVED
+	 *   as their real JS values (unlike JSON, which would lose them).
+	 * - A circular structure is PRESERVED, with each back-reference replaced by a
+	 *   `[Circular]` marker (it does NOT throw).
+	 * - Values with no transferable form (functions, symbols) come back as
+	 *   `undefined`; a `Date` comes back as a `Date`; `Map`/`Set` come back as an
+	 *   empty object `{}` (their entries do not survive the clone).
+	 * - Live host objects (a DOM node, `window`) come back as an OPAQUE PREVIEW
+	 *   STRING, NOT the live object: it cannot cross the process boundary, so the
+	 *   escape hatch hands back a readable stand-in rather than a broken handle.
+	 *   An agent that needs a DOM value reads a serializable property of it
+	 *   (`...textContent`, `...value`) inside the expression, exactly as the
+	 *   tests do.
+	 * - An expression that THROWS in the page REJECTS with a transport-neutral
+	 *   `Error` carrying the page-side message (no CDP/Playwright type leaks
+	 *   across the seam, ADR-0003).
+	 *
+	 * The return type is `unknown` because the page decides the shape; callers
+	 * narrow it. This is deliberately a thin passthrough to the transport's
+	 * serialize-and-return: `eval` does not re-encode or wrap the result, so an
+	 * agent gets exactly what the page produced.
+	 */
+	eval(expression: string): Promise<unknown>;
+	/** Pace actions by waiting for a condition. */
+	wait(condition: WaitCondition): Promise<void>;
+	/** Read the session's cookies. */
+	cookies(): Promise<readonly Cookie[]>;
+	/** Seed the session's cookies. */
+	setCookies(cookies: readonly Cookie[]): Promise<void>;
+}
+
+/**
+ * A live browser session owning one active {@link Page}. The session lifetime
+ * spans from {@link Transport.open} to {@link Session.close}; it is the unit a
+ * long-lived controller process keeps between CLI invocations (PRD
+ * "session/daemon question").
+ */
+export interface Session {
+	/** The active page the verbs act on. */
+	readonly page: Page;
+	/** Tear down the session and release the underlying browser resources. */
+	close(): Promise<void>;
+}
+
+/**
+ * The transport seam. A `Transport` (a.k.a. driver) knows how to OPEN a
+ * {@link Session} for a given {@link OpenTarget}. v1 concrete transport is
+ * Playwright (built in a later task); an extension or Firefox transport can
+ * implement the same interface.
+ */
+export interface Transport {
+	open(target: OpenTarget): Promise<Session>;
+}
+
+/** Alias: the seam is referred to as the `Driver` in the domain glossary. */
+export type Driver = Transport;

package/src/session-endpoint.ts

@@ -0,0 +1,104 @@
+import {mkdir, readFile, rm, writeFile} from 'node:fs/promises';
+import {dirname, join} from 'node:path';
+import {
+	resolveHomeRoot,
+	type ProfileLocationOptions,
+} from './profile-location.js';
+
+/**
+ * Cross-invocation session DISCOVERY (ADR-0005).
+ *
+ * The long-lived `incur serve` process owns the one live browser session; each
+ * `webhands <verb>` is a thin client that must FIND that running
+ * server. The server advertises itself by writing a small endpoint file under
+ * the controller home root (the same SHARED location profiles live under, see
+ * {@link resolveHomeRoot}); client verbs read it to learn where to send their
+ * verb calls. When no endpoint file exists, no server is live, and a verb errors
+ * with "run `serve` first" rather than auto-spawning a browser (ADR-0005:
+ * lifecycle is EXPLICIT in v1).
+ *
+ * Because this writes under the real `~/.webhands` by default,
+ * TESTS MUST override the root to a temp dir (via {@link ProfileLocationOptions})
+ * and assert the real location is untouched, exactly as the profile location
+ * does.
+ */
+
+/** The endpoint file name under the controller home root. */
+export const SESSION_ENDPOINT_FILENAME = 'session-endpoint.json';
+
+/**
+ * What the served process advertises about itself for client discovery. Kept
+ * deliberately small: the base `url` a client posts verb calls to, plus the
+ * `pid` so a human/test can confirm or signal the owning process.
+ */
+export interface SessionEndpoint {
+	/** The base HTTP URL the served session listens on (e.g. `http://127.0.0.1:53113`). */
+	readonly url: string;
+	/** The PID of the served process, for confirmation / signalling. */
+	readonly pid: number;
+}
+
+/**
+ * Resolve the absolute path of the endpoint file for a given home root. Pure
+ * (touches no filesystem); precedence matches {@link resolveHomeRoot} so the
+ * endpoint file always sits beside the profiles dir under the same root.
+ */
+export function resolveSessionEndpointPath(
+	options: ProfileLocationOptions = {},
+): string {
+	return join(resolveHomeRoot(options), SESSION_ENDPOINT_FILENAME);
+}
+
+/**
+ * Advertise a live served session by writing its endpoint file (creating the
+ * home root if absent). Overwrites any stale file; the server owns this file's
+ * lifetime and clears it on stop.
+ */
+export async function writeSessionEndpoint(
+	endpoint: SessionEndpoint,
+	options: ProfileLocationOptions = {},
+): Promise<string> {
+	const path = resolveSessionEndpointPath(options);
+	await mkdir(dirname(path), {recursive: true});
+	await writeFile(path, JSON.stringify(endpoint, null, 2), 'utf8');
+	return path;
+}
+
+/**
+ * Read the advertised endpoint, or `undefined` when no server is live (the file
+ * is absent or unreadable). Discovery is best-effort: a malformed file is
+ * treated as "no live server" so a client falls through to the clear
+ * "run `serve` first" error rather than crashing on a partial write.
+ */
+export async function readSessionEndpoint(
+	options: ProfileLocationOptions = {},
+): Promise<SessionEndpoint | undefined> {
+	const path = resolveSessionEndpointPath(options);
+	let text: string;
+	try {
+		text = await readFile(path, 'utf8');
+	} catch {
+		return undefined;
+	}
+	try {
+		const parsed = JSON.parse(text) as Partial<SessionEndpoint>;
+		if (
+			typeof parsed.url === 'string' &&
+			parsed.url !== '' &&
+			typeof parsed.pid === 'number'
+		) {
+			return {url: parsed.url, pid: parsed.pid};
+		}
+	} catch {
+		// fall through
+	}
+	return undefined;
+}
+
+/** Remove the endpoint file (teardown). Absent file is not an error. */
+export async function clearSessionEndpoint(
+	options: ProfileLocationOptions = {},
+): Promise<void> {
+	const path = resolveSessionEndpointPath(options);
+	await rm(path, {force: true});
+}

package/src/session-rpc.ts

@@ -0,0 +1,143 @@
+import {
+	locator,
+	type Cookie,
+	type Snapshot,
+	type WaitCondition,
+} from './seam.js';
+import type {Page} from './seam.js';
+
+/**
+ * The wire protocol for driving the long-lived session over HTTP (ADR-0005).
+ *
+ * The served process holds ONE live {@link Page} in memory; a thin client verb
+ * cannot hold a JS reference to it across the process boundary, so each verb
+ * call is sent as a small JSON request to the server, which runs it against its
+ * live page and returns the result. This module is the SINGLE source of truth
+ * for that request/response shape, imported by BOTH the server handler and the
+ * client proxy so they cannot drift (mirrors how `serializeCookies` is shared
+ * by the cookies verb and its test).
+ *
+ * It is a thin transport detail, NOT a second verb surface: every request maps
+ * 1:1 to a {@link Page} method, and the seam's verb semantics (ADR-0003/0004)
+ * are unchanged. The {@link LocatorString} brand and the structured
+ * {@link WaitCondition} cross as plain JSON and are re-branded on the server
+ * with {@link locator}; no Playwright/CDP type is ever named here.
+ */
+
+/** The path the session RPC is served under, below the server's base URL. */
+export const SESSION_RPC_PATH = '/session/call';
+
+/** A single verb call to run against the served live page. */
+export type SessionRpcRequest =
+	| {readonly verb: 'navigate'; readonly url: string}
+	| {readonly verb: 'snapshot'; readonly full?: boolean}
+	| {readonly verb: 'click'; readonly locator: string}
+	| {readonly verb: 'type'; readonly locator: string; readonly text: string}
+	| {readonly verb: 'eval'; readonly expression: string}
+	| {readonly verb: 'wait'; readonly condition: WaitCondition}
+	| {readonly verb: 'cookies'}
+	| {readonly verb: 'setCookies'; readonly cookies: readonly Cookie[]};
+
+/**
+ * The server's reply to a {@link SessionRpcRequest}. `ok: true` carries the
+ * verb's return value (for verbs that return data); `ok: false` carries the
+ * page-side error message so the client can re-throw a faithful `Error` (a
+ * page throw must REJECT on the client too, per the seam's `eval` contract).
+ */
+export type SessionRpcResponse =
+	| {readonly ok: true; readonly value?: unknown}
+	| {readonly ok: false; readonly error: string};
+
+/**
+ * Run one {@link SessionRpcRequest} against a live {@link Page}, returning the
+ * value the wire should carry back. The server's HTTP handler is just this plus
+ * JSON framing; keeping the dispatch here (not inline in the handler) means the
+ * verb-to-page mapping is in one place and unit-testable without HTTP.
+ *
+ * The locator string and wait condition arrive as plain JSON; we re-brand the
+ * locator with {@link locator} before handing it to the page so the seam's
+ * branded-string contract holds.
+ */
+export async function applySessionRpc(
+	page: Page,
+	request: SessionRpcRequest,
+): Promise<unknown> {
+	switch (request.verb) {
+		case 'navigate':
+			await page.navigate(request.url);
+			return undefined;
+		case 'snapshot':
+			return page.snapshot({full: request.full});
+		case 'click':
+			await page.click(locator(request.locator));
+			return undefined;
+		case 'type':
+			await page.type(locator(request.locator), request.text);
+			return undefined;
+		case 'eval':
+			return page.eval(request.expression);
+		case 'wait':
+			await page.wait(rebrandWait(request.condition));
+			return undefined;
+		case 'cookies':
+			return page.cookies();
+		case 'setCookies':
+			await page.setCookies(request.cookies);
+			return undefined;
+	}
+}
+
+/**
+ * A {@link Page} whose verbs forward to a server via the supplied transport.
+ *
+ * Used by the client-side proxy (see `remote-session.ts`): each verb builds a
+ * {@link SessionRpcRequest}, hands it to `send`, and shapes the reply back into
+ * the verb's return type. The `send` function owns the actual HTTP; this keeps
+ * the verb-to-request mapping (the other half of {@link applySessionRpc}) in
+ * one place so request and response shapes cannot drift between the two sides.
+ */
+export function makeRpcPage(
+	send: (request: SessionRpcRequest) => Promise<unknown>,
+): Page {
+	return {
+		async navigate(url) {
+			await send({verb: 'navigate', url});
+		},
+		async snapshot(options) {
+			return (await send({
+				verb: 'snapshot',
+				full: options?.full,
+			})) as Snapshot;
+		},
+		async click(target) {
+			await send({verb: 'click', locator: target});
+		},
+		async type(target, text) {
+			await send({verb: 'type', locator: target, text});
+		},
+		async eval(expression) {
+			return send({verb: 'eval', expression});
+		},
+		async wait(condition) {
+			await send({verb: 'wait', condition});
+		},
+		async cookies() {
+			return (await send({verb: 'cookies'})) as readonly Cookie[];
+		},
+		async setCookies(cookies) {
+			await send({verb: 'setCookies', cookies});
+		},
+	};
+}
+
+/**
+ * Re-brand a {@link WaitCondition} that arrived as plain JSON: only the
+ * `locator` form carries a branded string, which JSON flattens to a plain
+ * `string`, so we re-tag it before it reaches the page.
+ */
+function rebrandWait(condition: WaitCondition): WaitCondition {
+	if (condition.kind === 'locator') {
+		return {kind: 'locator', target: locator(condition.target)};
+	}
+	return condition;
+}