@webhands/core 0.1.0 → 0.2.0

package/src/hand-loading.ts

@@ -0,0 +1,254 @@
+import {readFile} from 'node:fs/promises';
+import {isAbsolute, resolve} from 'node:path';
+import {pathToFileURL} from 'node:url';
+import type {Hand} from './hand-host.js';
+
+/**
+ * Explicit, declarative third-party-hand loading (Phase 2 of the "hands" prd,
+ * `work/prds/tasked/hands-pluggable-page-capabilities.md`; ADR-0007).
+ *
+ * A third-party **hand** is in-process Node code the host will hand the live
+ * Playwright page (see {@link Hand}). Because that is arbitrary Node code in the
+ * webhands process — a strictly LARGER surface than `eval` (which is sandboxed
+ * to the page's JS world) — loading a hand is a TRUST act: the right mental
+ * model is npm supply-chain trust, "loading a hand == trusting an in-process npm
+ * dependency" (ADR-0007). This module makes that trust act EXPLICIT and
+ * DECLARATIVE, modeled on pi's `packages[]`:
+ *
+ * - A hand loads ONLY because it is NAMED in config ({@link HandsConfig}), each
+ *   entry carrying a PINNED entry point. NAMING a hand in config IS the trust
+ *   act.
+ * - There is NO auto-discovery, NO `node_modules` scan, NO convention-inferred
+ *   entry file. An installed-but-not-named hand never loads.
+ * - INSTALL is SEPARATE from LOAD/trust: `npm install <hand>` alone never
+ *   auto-loads it; the operator installs the dependency themselves (a managed
+ *   installer is explicitly OUT of scope) and then names it here to load it.
+ *
+ * The trust boundary stays LOCAL-only: hands widen the in-process surface, not
+ * the remote one (no new network listener). This module never installs, never
+ * scans a directory, and never reads anything beyond the entries the config
+ * explicitly names.
+ */
+
+/**
+ * One explicitly-named third-party hand. NAMING an entry here is the trust act
+ * (ADR-0007); webhands will load EXACTLY this entry and nothing it was not told
+ * about.
+ */
+export interface HandEntry {
+	/**
+	 * The operator-chosen identifier for this hand. Used in error messages and
+	 * to make the config self-documenting; it has no install side effect (naming
+	 * is the trust act, not an install instruction).
+	 */
+	readonly name: string;
+	/**
+	 * Descriptive provenance, e.g. `npm:@scope/hand` or `git:https://…`. Mirrors
+	 * pi's named-source shape. It is RECORDED, not acted on: webhands does NOT
+	 * install from it (install is separate from load/trust — the operator
+	 * installs the dependency themselves). Optional.
+	 */
+	readonly source?: string;
+	/**
+	 * The PINNED entry point: the exact module file webhands will `import()`. No
+	 * convention-inferred entry, no `package.json` `main` lookup, no directory
+	 * scan — the operator pins the file. A relative path is resolved against
+	 * {@link LoadHandsOptions.baseDir} (the config's own directory); an absolute
+	 * path is used as-is.
+	 */
+	readonly entry: string;
+}
+
+/**
+ * The webhands hand config: an EXPLICIT named list of third-party hands. Modeled
+ * on pi's `settings.json` `packages[]` (a named list of sources, each with a
+ * pinned entry). An empty/absent list means no third-party hands load.
+ */
+export interface HandsConfig {
+	readonly hands: readonly HandEntry[];
+}
+
+/** The filename webhands reads the hand config from, under the home root. */
+export const HANDS_CONFIG_FILENAME = 'hands.json';
+
+/** A loaded hand paired with the config entry that named it (for diagnostics). */
+export interface LoadedHand {
+	readonly entry: HandEntry;
+	readonly hand: Hand;
+}
+
+/** Options controlling how config entries resolve to modules. */
+export interface LoadHandsOptions {
+	/**
+	 * The base directory a relative {@link HandEntry.entry} resolves against.
+	 * Defaults to the current working directory. In production this is the
+	 * config's own directory; in tests it points at a scratch dir so the real
+	 * config/loading paths are never touched.
+	 */
+	readonly baseDir?: string;
+	/**
+	 * The importer used to load a pinned entry. Defaults to a dynamic `import()`
+	 * of the resolved file URL. Injectable so tests can load a fixture hand
+	 * without a real on-disk module.
+	 */
+	readonly importModule?: (specifier: string) => Promise<unknown>;
+}
+
+/**
+ * Error raised when a NAMED hand cannot be loaded: its pinned entry is missing,
+ * fails to import, or does not export a {@link Hand}. A named hand that fails to
+ * resolve is a hard error (not a silent skip) so a typo or a broken/half-removed
+ * dependency surfaces loudly rather than silently dropping a capability the
+ * operator explicitly trusted.
+ */
+export class HandLoadError extends Error {
+	readonly entry: HandEntry;
+	constructor(entry: HandEntry, detail: string, options?: {cause?: unknown}) {
+		super(
+			`failed to load hand '${entry.name}' (entry '${entry.entry}'): ${detail}`,
+			options,
+		);
+		this.name = 'HandLoadError';
+		this.entry = entry;
+	}
+}
+
+/**
+ * Read the hand config from `<homeRoot>/hands.json`. A missing file yields an
+ * EMPTY config (no third-party hands) — the default, install-separate-from-load
+ * posture: webhands loads nothing it was not explicitly told to. A present file
+ * that is malformed is a hard error (so a broken config is not silently treated
+ * as "no hands").
+ */
+export async function readHandsConfig(homeRoot: string): Promise<HandsConfig> {
+	const path = resolve(homeRoot, HANDS_CONFIG_FILENAME);
+	let raw: string;
+	try {
+		raw = await readFile(path, 'utf8');
+	} catch (cause) {
+		if ((cause as NodeJS.ErrnoException)?.code === 'ENOENT') {
+			return {hands: []};
+		}
+		throw cause;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new Error(`invalid hand config at ${path}: not valid JSON`, {cause});
+	}
+	return normalizeConfig(parsed, path);
+}
+
+/**
+ * Validate a parsed config object into a {@link HandsConfig}. Enforces the
+ * explicit-named-list + pinned-entry shape: every entry MUST carry a non-empty
+ * `name` and a non-empty `entry` (the pinned module). A missing/blank pin is
+ * rejected rather than guessed (no convention-inferred entry).
+ */
+export function normalizeConfig(
+	parsed: unknown,
+	whence = 'hand config',
+): HandsConfig {
+	if (parsed === null || typeof parsed !== 'object') {
+		throw new Error(`invalid ${whence}: expected an object`);
+	}
+	const handsValue = (parsed as {hands?: unknown}).hands;
+	if (handsValue === undefined) {
+		return {hands: []};
+	}
+	if (!Array.isArray(handsValue)) {
+		throw new Error(`invalid ${whence}: 'hands' must be an array`);
+	}
+	const hands = handsValue.map((value, i) => normalizeEntry(value, i, whence));
+	return {hands};
+}
+
+function normalizeEntry(value: unknown, i: number, whence: string): HandEntry {
+	if (value === null || typeof value !== 'object') {
+		throw new Error(`invalid ${whence}: hands[${i}] must be an object`);
+	}
+	const {name, entry, source} = value as Record<string, unknown>;
+	if (typeof name !== 'string' || name === '') {
+		throw new Error(
+			`invalid ${whence}: hands[${i}].name must be a non-empty string`,
+		);
+	}
+	if (typeof entry !== 'string' || entry === '') {
+		throw new Error(
+			`invalid ${whence}: hands[${i}].entry (the pinned entry point) must be a non-empty string`,
+		);
+	}
+	if (source !== undefined && typeof source !== 'string') {
+		throw new Error(`invalid ${whence}: hands[${i}].source must be a string`);
+	}
+	return source === undefined ? {name, entry} : {name, entry, source};
+}
+
+/**
+ * Load every hand NAMED in `config`, in declaration order. Each entry's pinned
+ * {@link HandEntry.entry} is resolved (relative ⇒ against
+ * {@link LoadHandsOptions.baseDir}) and imported; the module must export a
+ * {@link Hand} as its DEFAULT export or as a named `hand` export. A failure to
+ * resolve/import/validate a named hand throws {@link HandLoadError} (named hands
+ * fail loud, never silently skip).
+ *
+ * Loading nothing for an empty list is the whole point of the model: only the
+ * entries the operator explicitly named load, so an installed-but-not-named hand
+ * is never reached here.
+ */
+export async function loadHands(
+	config: HandsConfig,
+	options: LoadHandsOptions = {},
+): Promise<LoadedHand[]> {
+	const baseDir = options.baseDir ?? process.cwd();
+	const importModule =
+		options.importModule ??
+		((specifier) => import(specifier) as Promise<unknown>);
+
+	const loaded: LoadedHand[] = [];
+	for (const entry of config.hands) {
+		const specifier = resolveEntrySpecifier(entry.entry, baseDir);
+		let mod: unknown;
+		try {
+			mod = await importModule(specifier);
+		} catch (cause) {
+			throw new HandLoadError(entry, 'could not import the pinned entry', {
+				cause,
+			});
+		}
+		const hand = extractHand(mod);
+		if (hand === undefined) {
+			throw new HandLoadError(
+				entry,
+				'the module does not export a Hand (expected a default export or a named `hand` export that is a function)',
+			);
+		}
+		loaded.push({entry, hand});
+	}
+	return loaded;
+}
+
+/**
+ * Resolve a pinned entry to an import specifier. A relative/absolute filesystem
+ * path is resolved against `baseDir` and converted to a `file://` URL (so a
+ * Windows path or a path with spaces imports correctly); anything else is passed
+ * through verbatim (the operator may pin a bare package specifier they have
+ * installed themselves — webhands does not install it).
+ */
+function resolveEntrySpecifier(entry: string, baseDir: string): string {
+	if (isAbsolute(entry) || entry.startsWith('.')) {
+		return pathToFileURL(resolve(baseDir, entry)).href;
+	}
+	return entry;
+}
+
+/** Pull a {@link Hand} out of an imported module (default or named `hand`). */
+function extractHand(mod: unknown): Hand | undefined {
+	if (mod === null || typeof mod !== 'object') {
+		return undefined;
+	}
+	const record = mod as Record<string, unknown>;
+	const candidate = record.default ?? record.hand;
+	return typeof candidate === 'function' ? (candidate as Hand) : undefined;
+}

package/src/index.ts

@@ -3,7 +3,7 @@ export type {
 	Driver,
 	LocatorString,
 	OpenTarget,
-	Page,
+	WebHandsPage,
 	Session,
 	Snapshot,
 	SnapshotOptions,
@@ -22,6 +22,20 @@ export {
 
 export {StubTransport, type StubCall} from './stub-transport.js';
 
+export type {Hand, HandContext, HandContribution} from './hand-host.js';
+
+export {
+	readHandsConfig,
+	normalizeConfig,
+	loadHands,
+	HandLoadError,
+	HANDS_CONFIG_FILENAME,
+	type HandEntry,
+	type HandsConfig,
+	type LoadedHand,
+	type LoadHandsOptions,
+} from './hand-loading.js';
+
 export {PlaywrightLaunchTransport} from './playwright-launch-transport.js';
 
 export {PlaywrightAttachTransport} from './playwright-attach-transport.js';
@@ -68,7 +82,10 @@ export {
 	SESSION_RPC_PATH,
 	applySessionRpc,
 	makeRpcPage,
+	callHandVerb,
 	type SessionRpcRequest,
+	type SessionRpcBuiltInRequest,
+	type SessionRpcHandRequest,
 	type SessionRpcResponse,
 } from './session-rpc.js';
 

package/src/playwright-attach-transport.ts

@@ -2,24 +2,11 @@ import {
 	chromium,
 	type Browser,
 	type BrowserContext,
-	type Page as PwPage,
+	type Page,
 } from 'playwright';
 import {AttachNoContextError, AttachNotChromiumError} from './errors.js';
-import {
-	clickLocator,
-	resolveLocator,
-	waitFor,
-} from './playwright-launch-transport.js';
-import type {
-	Cookie,
-	OpenTarget,
-	Page,
-	Session,
-	Snapshot,
-	SnapshotOptions,
-	Transport,
-	WaitCondition,
-} from './seam.js';
+import {composeWithHands, type Hand, type HandContext} from './hand-host.js';
+import type {OpenTarget, Session, Transport} from './seam.js';
 
 /**
  * The `attach` concrete transport: connect (`chromium.connectOverCDP`) to a
@@ -45,6 +32,18 @@ import type {
  * running one.
  */
 export class PlaywrightAttachTransport implements Transport {
+	readonly #hands: readonly Hand[];
+
+	/**
+	 * @param hands explicitly-loaded third-party hands to compose alongside the
+	 *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
+	 *   the operator's explicit config; the transport does NOT discover them. Omit
+	 *   for the built-ins-only surface.
+	 */
+	constructor(hands: readonly Hand[] = []) {
+		this.#hands = hands;
+	}
+
 	async open(target: OpenTarget): Promise<Session> {
 		if (target.mode !== 'attach') {
 			throw new Error(
@@ -78,7 +77,7 @@ export class PlaywrightAttachTransport implements Transport {
 			// browser exposes a context with no page yet (single active session in
 			// v1, PRD Out of Scope).
 			const pwPage = context.pages()[0] ?? (await context.newPage());
-			return makeAttachedSession(browser, pwPage);
+			return makeAttachedSession(browser, pwPage, this.#hands);
 		} catch (cause) {
 			// On any open-time refusal, disconnect from the user's browser without
 			// closing it (a CDP connection close detaches; it does not kill the
@@ -92,13 +91,23 @@ export class PlaywrightAttachTransport implements Transport {
 /**
  * Wrap a CDP-attached browser into the seam's {@link Session}.
  *
- * `close()` DISCONNECTS the controller from the user's browser; it must not
- * kill the browser the user started (`Browser.close()` on a `connectOverCDP`
- * connection detaches rather than terminating the remote process). We resolve
- * cookies through the reused context so they reflect the live, authenticated
- * session.
+ * The VERB surface comes from the shared hand-host ({@link composeBuiltInPage}),
+ * the SAME single composition the launch transport uses (no duplicated
+ * page-object literal). Cookies resolve through the reused context (derived here
+ * via `pwPage.context()`) so they reflect the live, authenticated session.
+ *
+ * Only the SESSION LIFECYCLE is per-transport: this transport listens on the
+ * browser's `'disconnected'` event and its `close()` calls `browser.close()`,
+ * which DISCONNECTS the controller from the user's browser WITHOUT killing it
+ * (a `connectOverCDP` connection detaches rather than terminating the remote
+ * process, ADR-0002) — the opposite of the launch transport, which kills the
+ * browser it spawned.
  */
-function makeAttachedSession(browser: Browser, pwPage: PwPage): Session {
+function makeAttachedSession(
+	browser: Browser,
+	pwPage: Page,
+	extraHands: readonly Hand[],
+): Session {
 	const context: BrowserContext = pwPage.context();
 	let closed = false;
 	const ensureOpen = () => {
@@ -107,108 +116,45 @@ function makeAttachedSession(browser: Browser, pwPage: PwPage): Session {
 		}
 	};
 
-	const page: Page = {
-		async navigate(url: string): Promise<void> {
-			ensureOpen();
-			// "Settled" = the `load` event; XHR/JS-rendered content that appears
-			// after load is the `wait` verb's job. Same rationale (and the
-			// no-`networkidle` reasoning) as the launch transport's `navigate`.
-			await pwPage.goto(url, {waitUntil: 'load'});
-		},
-		async snapshot(options?: SnapshotOptions): Promise<Snapshot> {
-			ensureOpen();
-			const url = pwPage.url();
-			if (options?.full === true) {
-				const content = await pwPage.evaluate(
-					() => document.documentElement.outerHTML,
-				);
-				return {url, view: 'full', content};
-			}
-			// Default: the token-cheap accessibility tree + visible text with stable
-			// `[ref=...]` refs (see the launch transport and `Snapshot` for the
-			// rationale; the string crosses the seam as opaque, transport-neutral
-			// text, ADR-0003).
-			const content = await pwPage.ariaSnapshot({mode: 'ai'});
-			return {url, view: 'accessibility', content};
-		},
-		// `resolveLocator`/`clickLocator`/`waitFor` are imported from the launch
-		// transport so both transports resolve locators and run the verbs through
-		// ONE path (no parallel addressing scheme; the forward-note).
-		async click(t): Promise<void> {
-			ensureOpen();
-			// Shared `clickLocator`: normal actionability-checked click with the
-			// hidden-element dispatch fallback (PRD story 8), identical to launch.
-			await clickLocator(pwPage, t);
-		},
-		async type(t, text): Promise<void> {
-			ensureOpen();
-			await resolveLocator(pwPage, t).fill(text);
-		},
-		async eval(expression: string): Promise<unknown> {
-			ensureOpen();
-			return pwPage.evaluate(expression);
-		},
-		async wait(condition: WaitCondition): Promise<void> {
-			ensureOpen();
-			// Identical to the launch transport (shared `waitFor`): selector /
-			// navigation / timeout, so the verb behaves the same on both.
-			await waitFor(pwPage, condition);
-		},
-		async cookies(): Promise<readonly Cookie[]> {
-			ensureOpen();
-			const raw = await context.cookies();
-			return raw.map(toSeamCookie);
-		},
-		async setCookies(cookies): Promise<void> {
-			ensureOpen();
-			await context.addCookies(cookies.map(fromSeamCookie));
-		},
+	// Resolves when the session ends: either the user's browser goes away
+	// (Playwright fires 'disconnected' on a connectOverCDP browser) or our own
+	// close() disconnects. Lets a caller block until the session is gone.
+	let resolveClosed!: () => void;
+	const closedSignal = new Promise<void>((resolve) => {
+		resolveClosed = resolve;
+	});
+	const markClosed = () => {
+		if (closed) return;
+		closed = true;
+		resolveClosed();
 	};
+	browser.on('disconnected', markClosed);
+
+	// Build the verb surface from the built-in hands over a live hand-context —
+	// the same shared host the launch transport uses, so the verbs behave
+	// identically across both transports. The live `pwPage`/`context` stay
+	// in-process and never cross the seam (ADR-0003).
+	const handContext: HandContext = {pwPage, context, ensureOpen};
+	const {page, dispose: disposeHands} = composeWithHands(
+		handContext,
+		extraHands,
+	);
 
 	return {
 		page,
 		async close(): Promise<void> {
-			if (closed) return;
-			closed = true;
-			// Detach from the user's browser; do NOT terminate it.
+			if (closed) {
+				return;
+			}
+			// Dispose the hands first (their in-process resources), THEN detach from
+			// the user's browser without terminating it. browser.close() fires
+			// 'disconnected', which runs markClosed.
+			await disposeHands();
 			await browser.close();
+			markClosed();
+		},
+		waitForClose(): Promise<void> {
+			return closedSignal;
 		},
-	};
-}
-
-/** Map a Playwright cookie to the transport-neutral seam {@link Cookie}. */
-function toSeamCookie(c: {
-	name: string;
-	value: string;
-	domain?: string;
-	path?: string;
-	expires?: number;
-	httpOnly?: boolean;
-	secure?: boolean;
-	sameSite?: 'Strict' | 'Lax' | 'None';
-}): Cookie {
-	return {
-		name: c.name,
-		value: c.value,
-		domain: c.domain,
-		path: c.path,
-		expires: c.expires,
-		httpOnly: c.httpOnly,
-		secure: c.secure,
-		sameSite: c.sameSite,
-	};
-}
-
-/** Map a seam {@link Cookie} to a Playwright cookie shape. */
-function fromSeamCookie(c: Cookie) {
-	return {
-		name: c.name,
-		value: c.value,
-		domain: c.domain,
-		path: c.path,
-		expires: c.expires,
-		httpOnly: c.httpOnly,
-		secure: c.secure,
-		sameSite: c.sameSite,
 	};
 }