@webhands/core 0.1.0 → 0.3.0

package/dist/hand-host.js

@@ -0,0 +1,351 @@
+import { errors as pwErrors } from 'playwright';
+/**
+ * Compose a set of hands over one live {@link HandContext} into a single
+ * {@link WebHandsPage}. This is the host primitive both Playwright transports call to
+ * build their session's verb surface — the SINGLE shared composition (no
+ * duplicated page-object literal).
+ *
+ * Composition is EAGER (exactly as the page object literal was built before):
+ * each hand is invoked once at session-open time and its verbs are merged into
+ * one page object. There is no lazy registration and no ordering effect on the
+ * verbs themselves (the eight built-in verbs have disjoint names). The returned
+ * {@link WebHandsPage} is validated to carry every verb the seam requires, so a missing
+ * built-in verb is a build-time/open-time failure here rather than an `undefined
+ * is not a function` at the call site.
+ */
+export function composePage(ctx, hands) {
+    const verbs = {};
+    const disposers = [];
+    for (const hand of hands) {
+        const contribution = hand(ctx);
+        Object.assign(verbs, contribution.verbs);
+        if (contribution.dispose !== undefined) {
+            disposers.push(contribution.dispose);
+        }
+    }
+    const page = assertCompletePage(verbs);
+    return {
+        page,
+        async dispose() {
+            // LIFO teardown; await every disposer even if one rejects so a single
+            // failing hand cannot strand the others' cleanup.
+            const failures = [];
+            for (let i = disposers.length - 1; i >= 0; i--) {
+                try {
+                    await disposers[i]();
+                }
+                catch (cause) {
+                    failures.push(cause);
+                }
+            }
+            if (failures.length > 0) {
+                throw failures[0];
+            }
+        },
+    };
+}
+/** The seam's full verb set; used to validate a composed page is complete. */
+const REQUIRED_VERBS = [
+    'navigate',
+    'snapshot',
+    'click',
+    'type',
+    'eval',
+    'wait',
+    'cookies',
+    'setCookies',
+];
+/**
+ * Assert the composed verbs cover the whole seam {@link WebHandsPage}, then return it
+ * as a `WebHandsPage`. A gap here means a built-in hand was dropped from the
+ * composition — surfacing it at open time is far cheaper than a runtime
+ * `undefined is not a function`.
+ */
+function assertCompletePage(verbs) {
+    const missing = REQUIRED_VERBS.filter((name) => typeof verbs[name] !== 'function');
+    if (missing.length > 0) {
+        throw new Error(`hand-host: composed page is missing verb(s): ${missing.join(', ')}`);
+    }
+    return verbs;
+}
+/**
+ * How long a normal, actionability-checked `click` may wait before we treat the
+ * element as un-clickable and fall back to a dispatched click. Short on purpose:
+ * a hidden custom input never becomes actionable, so the regular click would
+ * otherwise burn Playwright's full default timeout (30s) before the escape path
+ * runs. The visible-element happy path clicks immediately and never hits this;
+ * this bound is the latency cost paid ONLY on the hidden/non-actionable path,
+ * and is long enough to tolerate a slow-but-eventually-actionable element
+ * (animations, late layout) before deciding to dispatch.
+ */
+const NORMAL_CLICK_TIMEOUT_MS = 1_000;
+// ---------------------------------------------------------------------------
+// Built-in hands: webhands' OWN eight verbs, each a hand over the host.
+//
+// Grouped into cohesive capability modules (navigation, snapshot, interaction,
+// eval, wait, cookies) to demonstrate that a hand can contribute several verbs
+// + in-process logic (it is NOT one-verb-per-hand). The verb BODIES are moved
+// verbatim from the two transports' page-object literals, so behavior is
+// preserved byte-for-byte (the existing verb suite is the proof).
+// ---------------------------------------------------------------------------
+/** The `navigate` verb: go to a URL and let it settle on the `load` event. */
+export const navigationHand = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async navigate(url) {
+            ensureOpen();
+            // "Settled" for `goto` = the `load` event: the document and its
+            // subresources have loaded (PRD story 6, "navigate ... and wait for it
+            // to settle"). We deliberately do NOT wait for `networkidle`:
+            // Playwright discourages it, and it hangs forever on pages with
+            // long-poll / streaming / analytics beacons (exactly the logged-in apps
+            // this tool targets). Content rendered AFTER load (XHR-injected prices,
+            // hydrated lists) is the job of the explicit `wait` verb (story 10), not
+            // of `goto`.
+            await pwPage.goto(url, { waitUntil: 'load' });
+        },
+    },
+});
+/** The `snapshot` verb: the token-cheap a11y view, or `--full` raw DOM. */
+export const snapshotHand = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async snapshot(options) {
+            ensureOpen();
+            const url = pwPage.url();
+            if (options?.full === true) {
+                // `--full`: the raw DOM. `documentElement.outerHTML` is the serialized
+                // live DOM (post-script render), which is what an agent that wants the
+                // real HTML expects — not the original network response.
+                const content = await pwPage.evaluate(() => document.documentElement.outerHTML);
+                return { url, view: 'full', content };
+            }
+            // Default: the token-cheap accessibility tree + visible text with stable
+            // `[ref=...]` element refs. Playwright's `ariaSnapshot({mode: 'ai'})`
+            // emits exactly that — a YAML aria tree (roles + accessible names +
+            // text) where each node carries a stable `[ref=eN]` reference, assigned
+            // deterministically by traversal order so re-snapshotting an unchanged
+            // page yields the same refs. The string crosses the seam as opaque,
+            // transport-neutral text (no Playwright type leaks, ADR-0003).
+            const content = await pwPage.ariaSnapshot({ mode: 'ai' });
+            return { url, view: 'accessibility', content };
+        },
+    },
+});
+/** The `click` + `type` verbs: page interaction by raw locator (ADR-0004). */
+export const interactionHand = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async click(t) {
+            ensureOpen();
+            await clickLocator(pwPage, t);
+        },
+        async type(t, text) {
+            ensureOpen();
+            await resolveLocator(pwPage, t).fill(text);
+        },
+    },
+});
+/** The `eval` escape hatch: run a JS EXPRESSION in the page, return by value. */
+export const evalHand = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async eval(expression) {
+            ensureOpen();
+            // The `eval` escape hatch (PRD story 9): run the raw JS EXPRESSION in the
+            // page and return its serializable result. Playwright's `evaluate`
+            // already IS the seam's serialization contract (see {@link WebHandsPage.eval}):
+            // it passes a string as an expression, awaits a returned Promise, and
+            // structurally clones the result out of the page by VALUE. That clone is
+            // richer than JSON: it preserves NaN/Infinity/BigInt and circular
+            // structures (back-refs become a `[Circular]` marker), yields `undefined`
+            // for functions/symbols, and returns an opaque preview string for a live
+            // host object (a DOM node never crosses the process boundary). A page-side
+            // throw rejects. We pass it straight through rather than re-encode it:
+            // wrapping the value in a transport-specific envelope would invent a
+            // dialect the seam deliberately avoids. The thrown error is a plain
+            // `Error`, so no Playwright/CDP type leaks across the seam (ADR-0003).
+            return pwPage.evaluate(expression);
+        },
+    },
+});
+/** The `wait` verb: pace actions by a condition (timeout/locator/navigation). */
+export const waitHand = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async wait(condition) {
+            ensureOpen();
+            await waitFor(pwPage, condition);
+        },
+    },
+});
+/**
+ * The `cookies` + `setCookies` verbs. These prove the {@link HandContext} needs
+ * the `context`: cookies are a context-level, not page-level, concern, so this
+ * hand reaches `ctx.context`, not `ctx.pwPage`.
+ */
+export const cookiesHand = ({ context, ensureOpen }) => ({
+    verbs: {
+        async cookies() {
+            ensureOpen();
+            const raw = await context.cookies();
+            return raw.map(toSeamCookie);
+        },
+        async setCookies(cookies) {
+            ensureOpen();
+            await context.addCookies(cookies.map(fromSeamCookie));
+        },
+    },
+});
+/**
+ * webhands' eight built-in verbs as built-in hands, in composition order. Both
+ * Playwright transports compose THIS exact set, so the verb surface is
+ * identical across launch and attach (the only legitimate difference is the
+ * per-transport SESSION LIFECYCLE, which is not a hand's concern).
+ */
+export const BUILT_IN_HANDS = [
+    navigationHand,
+    snapshotHand,
+    interactionHand,
+    evalHand,
+    waitHand,
+    cookiesHand,
+];
+/**
+ * Compose webhands' built-in hands over a live context into the seam's
+ * {@link WebHandsPage}. The convenience both transports call: `composePage(ctx,
+ * BUILT_IN_HANDS)`. The built-in hands set up no in-process resources, so the
+ * returned `dispose` is a no-op today; it exists so a transport can sequence
+ * hand-teardown before its own browser/context teardown once third-party hands
+ * (which may hold resources) are added in Phase 2.
+ */
+export function composeBuiltInPage(ctx) {
+    return composePage(ctx, BUILT_IN_HANDS);
+}
+/**
+ * Compose webhands' built-in hands together with any explicitly-loaded
+ * third-party hands (Phase 2) over a live context. The third-party hands are
+ * composed AFTER the built-ins through the EXACT same {@link composePage} the
+ * built-ins use, so a loaded hand plugs into the same host: its verbs merge into
+ * the same seam {@link WebHandsPage} and its `dispose` is sequenced LIFO with the rest.
+ * A third-party hand may add NEW verbs (the common case) and, because later
+ * contributions win the merge, may also override a built-in verb — that is the
+ * operator's choice, made by the trust act of naming the hand (ADR-0007).
+ */
+export function composeWithHands(ctx, extraHands) {
+    return composePage(ctx, [...BUILT_IN_HANDS, ...extraHands]);
+}
+// ---------------------------------------------------------------------------
+// Shared verb building blocks (moved here with the verb bodies they back).
+// Re-exported from the launch transport for its existing public-API consumers.
+// ---------------------------------------------------------------------------
+/**
+ * Run the `wait` verb's three forms (PRD story 10) against a Playwright page.
+ *
+ * - `timeout` — pace by a fixed delay (`waitForTimeout`), so an agent can act
+ *   like a human and let XHR-rendered content land.
+ * - `locator` — block until the addressed element appears (`Locator.waitFor()`),
+ *   the form for content rendered AFTER `goto` settled on `load`.
+ * - `navigation` — block until the NEXT navigation settles to `load`. We use
+ *   `waitForNavigation()` even though Playwright marks it `@deprecated` ("racy,
+ *   use waitForURL"): that deprecation targets in-process TEST code that can arm
+ *   the wait BEFORE the action and pass a target URL. Neither holds here. Across
+ *   this seam verbs are DISCRETE sequential calls (`click` then `wait`), so we
+ *   CANNOT arm before the trigger; and the realistic trigger is an async,
+ *   JS-driven transition (a redirect / SPA route change that fires AFTER the
+ *   agent's action, the "let XHR-rendered content load" case of story 10), so
+ *   "wait for the NEXT navigation" is exactly right — whereas `waitForLoadState`
+ *   would see the already-loaded current page and return before the pending
+ *   transition. `waitForURL` is unusable because the verb has no target URL by
+ *   design (the agent waits for "a navigation", not a known address). (See the
+ *   task's ## Decisions note.)
+ *
+ * Shared by both Playwright transports (via the `wait` built-in hand) so the
+ * verb behaviour stays identical (no parallel second implementation).
+ */
+export async function waitFor(page, condition) {
+    switch (condition.kind) {
+        case 'timeout':
+            await page.waitForTimeout(condition.ms);
+            return;
+        case 'locator':
+            await resolveLocator(page, condition.target).waitFor();
+            return;
+        case 'navigation':
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            await page.waitForNavigation();
+            return;
+    }
+}
+/**
+ * Resolve a raw Playwright locator EXPRESSION (ADR-0004) against the page. The
+ * verb surface passes locator expressions like `getByRole('button', …)`; we
+ * evaluate them in a small sandbox where `page`/`p` is the page, so the full
+ * Playwright locator grammar is available without leaking the type across the
+ * seam.
+ *
+ * One resolution path for both transports (via the built-in interaction/wait
+ * hands), so there is no parallel addressing scheme.
+ */
+export function resolveLocator(page, expression) {
+    // eslint-disable-next-line no-new-func
+    const factory = new Function('page', 'p', `return (${expression});`);
+    return factory(page, page);
+}
+/**
+ * Run the `click` verb against a Playwright page (PRD story 8), shared by both
+ * Playwright transports (via the built-in interaction hand) so the verb behaves
+ * identically (mirrors {@link waitFor}; no parallel second implementation).
+ *
+ * First try a normal `Locator.click()`, which AUTO-WAITS for the element to be
+ * visible and actionable — the right behaviour for a real button. A hidden
+ * custom input (the case the prd calls out) NEVER becomes actionable, so that
+ * click times out; on a Playwright `TimeoutError` we fall back to
+ * `dispatchEvent('click')`, which fires a click WITHOUT the actionability
+ * checks. The fallback is deliberately the documented Playwright escape (a
+ * sibling to the `eval` hatch, ADR-0004), not a reimplemented click: we keep
+ * the locator a raw resolved expression and only change HOW the resolved
+ * locator is clicked.
+ *
+ * Only a timeout triggers the fallback. The fallback `dispatchEvent` is itself
+ * bounded by the same short timeout, so a locator that resolves NO element (a
+ * bad locator) surfaces its timeout quickly instead of hanging the dispatch on
+ * Playwright's 30s default — the dispatch escape is for elements that EXIST but
+ * are not actionable (hidden custom inputs), not for absent ones.
+ */
+export async function clickLocator(page, expression) {
+    const target = resolveLocator(page, expression);
+    try {
+        await target.click({ timeout: NORMAL_CLICK_TIMEOUT_MS });
+    }
+    catch (cause) {
+        if (!(cause instanceof pwErrors.TimeoutError)) {
+            throw cause;
+        }
+        // The element never became actionable (e.g. a hidden custom input). Fire
+        // the click without actionability checks, the prd's explicit escape path.
+        await target.dispatchEvent('click', { timeout: NORMAL_CLICK_TIMEOUT_MS });
+    }
+}
+/** Map a Playwright cookie to the transport-neutral seam {@link Cookie}. */
+function toSeamCookie(c) {
+    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) {
+    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,
+    };
+}
+//# sourceMappingURL=hand-host.js.map

package/dist/hand-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-host.js","sourceRoot":"","sources":["../src/hand-host.ts"],"names":[],"mappings":"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"}

package/dist/hand-loading.d.ts

@@ -0,0 +1,128 @@
+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 declare 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 declare class HandLoadError extends Error {
+    readonly entry: HandEntry;
+    constructor(entry: HandEntry, detail: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function readHandsConfig(homeRoot: string): Promise<HandsConfig>;
+/**
+ * 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 declare function normalizeConfig(parsed: unknown, whence?: string): HandsConfig;
+/**
+ * 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 declare function loadHands(config: HandsConfig, options?: LoadHandsOptions): Promise<LoadedHand[]>;
+//# sourceMappingURL=hand-loading.d.ts.map

package/dist/hand-loading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-loading.d.ts","sourceRoot":"","sources":["../src/hand-loading.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACrC;AAED,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,kFAAkF;AAClF,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACpB;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChE;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;gBACd,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAQzE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAkB5E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,OAAO,EACf,MAAM,SAAgB,GACpB,WAAW,CAab;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,gBAAqB,GAC5B,OAAO,CAAC,UAAU,EAAE,CAAC,CA2BvB"}

package/dist/hand-loading.js

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The filename webhands reads the hand config from, under the home root. */
+export const HANDS_CONFIG_FILENAME = 'hands.json';
+/**
+ * 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 {
+    entry;
+    constructor(entry, detail, options) {
+        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) {
+    const path = resolve(homeRoot, HANDS_CONFIG_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (cause) {
+        if (cause?.code === 'ENOENT') {
+            return { hands: [] };
+        }
+        throw cause;
+    }
+    let parsed;
+    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, whence = 'hand config') {
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new Error(`invalid ${whence}: expected an object`);
+    }
+    const handsValue = parsed.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, i, whence) {
+    if (value === null || typeof value !== 'object') {
+        throw new Error(`invalid ${whence}: hands[${i}] must be an object`);
+    }
+    const { name, entry, source } = value;
+    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, options = {}) {
+    const baseDir = options.baseDir ?? process.cwd();
+    const importModule = options.importModule ??
+        ((specifier) => import(specifier));
+    const loaded = [];
+    for (const entry of config.hands) {
+        const specifier = resolveEntrySpecifier(entry.entry, baseDir);
+        let mod;
+        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, baseDir) {
+    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) {
+    if (mod === null || typeof mod !== 'object') {
+        return undefined;
+    }
+    const record = mod;
+    const candidate = record.default ?? record.hand;
+    return typeof candidate === 'function' ? candidate : undefined;
+}
+//# sourceMappingURL=hand-loading.js.map

package/dist/hand-loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-loading.js","sourceRoot":"","sources":["../src/hand-loading.ts"],"names":[],"mappings":"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"}