webhands 0.0.0 → 0.1.7

package/README.md

@@ -0,0 +1,177 @@
+# webhands
+
+A CLI (built with [`incur`](https://github.com/wevm/incur), so it doubles as an
+MCP server) that drives a real, persistent browser via Playwright, letting an
+agent or human control any website from a genuinely logged-in browser session on
+their own machine and IP.
+
+It launches (or attaches to) a Chromium browser using a dedicated profile,
+supports a one-time headed login that is later reused headless, keeps the session
+alive across separate CLI invocations behind a long-lived `serve` process, and
+exposes page verbs (`goto`, `snapshot`, `click`, `type`, `eval`, `wait`,
+`cookies`) with structured output.
+
+## Use it via your AI agent (start here)
+
+The simplest way to use `webhands` is to let your coding agent (Claude Code,
+Cursor, etc.) run it through plain `bash` with `npx`. No MCP wiring, no install
+step — the agent just runs `npx webhands <verb>` commands. The first run of
+`npx webhands` fetches the package automatically.
+
+Give your agent something like: *"Use `webhands` to open Kayak and read me the
+live prices for EDI→BOM on 31 Oct."* A capable agent will then:
+
+```sh
+# 1. start & HOLD the browser. serve blocks, so the agent backgrounds it:
+nohup npx webhands serve --headed > /tmp/webhands.log 2>&1 &
+sleep 12 && cat /tmp/webhands.log     # confirm it printed an endpoint + pid
+
+# 2. navigate the live page (separate invocation, same browser):
+npx webhands goto 'https://www.kayak.co.uk/flights/EDI-BOM/2026-10-31?sort=price_a'
+
+# 3. let JS results render, then read the page token-cheaply:
+npx webhands wait --ms 8000
+npx webhands snapshot --token-limit 6000
+
+# 4. always tear down when done:
+npx webhands stop
+```
+
+Three things a new user should know up front:
+
+- **You log in once, in a window you can see.** Run `npx webhands setup-profile`
+  (or start with `serve --headed`) and sign in / clear any cookie or anti-bot
+  prompt yourself. That state is saved to a dedicated profile and reused on later
+  runs. The tool never bypasses logins or solves CAPTCHAs — you do that part.
+- **It acts as the real, logged-in you.** Reading pages is low-risk; let the agent
+  do that freely. But anything that spends money, books, posts, or changes account
+  state should be YOUR explicit decision — have the agent surface the link and let
+  you finish checkout. (See *Scope and honesty* below.)
+- **Anti-bot sites may need the visible window.** Headless runs can hit a
+  "you look like a bot" page on sites like Kayak. The fix is to run `--headed` and
+  clear the challenge yourself once, not to defeat it.
+
+For the full agent playbook (workflow, gotchas, guardrails) install the bundled
+skill: `npx webhands skills add` then look for `use-webhands`. Per-verb flag
+reference: `npx webhands <verb> --help` or `npx webhands --llms-full`.
+
+## How it works (the pipe)
+
+The browser is owned by ONE long-lived `serve` process; each verb invocation is a
+thin client that drives the SAME live page and exits (see
+[`docs/adr/0005`](docs/adr/0005-incur-serve-hosts-the-long-lived-session.md)). The
+typical end-to-end flow:
+
+1. `webhands setup-profile`: opens the dedicated profile in a
+   VISIBLE browser so you log in / clear any anti-bot challenge ONCE. State
+   (cookies, login, challenge clearance) persists on disk.
+2. `webhands serve --headless`: launches the one browser against
+   that saved profile and keeps it alive (runs until `stop` or Ctrl-C).
+3. `webhands goto <url>` then `webhands snapshot` (and
+   `click` / `type` / `eval` / `wait`): separate invocations that all drive the
+   single live page the server holds.
+4. `webhands stop`: tears the session down.
+
+A verb run with no live server prints a clear error telling you to run `serve`
+first; the tool never silently spawns a browser.
+
+## Scope and honesty (please read)
+
+This is a **personal-use** tool. Its whole premise is that you drive a browser
+**you logged into yourself**, on **your own machine and your own IP**, reusing
+**your own authenticated session** (see
+[`docs/adr/0002`](docs/adr/0002-real-session-over-fingerprint-spoofing.md)). It is
+deliberately local and single-session by design.
+
+- **No login-bypass, no CAPTCHA-solving.** The human does the one-time login and
+  clears any anti-bot challenge in the headed `setup-profile` step. This tool
+  does NOT bypass authentication or solve CAPTCHAs programmatically, and it is not
+  intended to.
+- **No fingerprint-spoofing / anti-detect tricks.** It leans on being a *real*
+  browser/profile/IP rather than spoofing. There is no proxy rotation or
+  anti-detect build here.
+- **Your own session only.** A replayed/stolen cookie does not work anyway
+  (clearance is bound to the browser fingerprint and IP, not just the cookie);
+  the design assumes the session is genuinely yours.
+
+In short: this is for reading and acting on web apps **you already have an account
+on**, from **your own browser**, the way you could by hand.
+
+## Optional: stealth launch (opt-in, default OFF)
+
+Standard Playwright drives Chromium over CDP and calls `Runtime.enable` at
+startup. That emits a side-effect a few lines of page JS can detect, and some
+anti-bot WAFs (Imperva/Cloudflare/DataDome) use it to serve an "Access Denied"
+block page *before the page even renders* — even on a real residential IP, even
+headed. `@webhands/core` can optionally launch via
+[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (an
+API-compatible Playwright fork that patches exactly these CDP leaks) to remove
+that one tell.
+
+This is **off by default** — vanilla Playwright stays the default. To enable it:
+
+1. Install the optional dependency (it is NOT pulled in unless you ask for it):
+
+   ```sh
+   pnpm add patchright
+   # if you do NOT pass --use-system-browser chrome, also fetch its browser:
+   #   pnpm exec patchright install chromium
+   ```
+
+2. Bring the session up with `--stealth`. The realistic recipe also drives your
+   installed system browser (`--use-system-browser chrome`), headed, against a
+   **warmed, logged-in profile**:
+
+   ```sh
+   # serve consumes these (it is where the browser is launched, ADR-0005):
+   npx webhands serve --headed --stealth --use-system-browser chrome
+   ```
+
+   `--use-system-browser` is independent of `--stealth`: you can drive real
+   Chrome with or without the Patchright path, and stealth with or without a
+   system browser. Other channel names work too (e.g. `msedge`).
+
+Programmatic equivalent (the `--stealth` / `--use-system-browser` flags map onto
+these transport options):
+
+```ts
+import {PlaywrightLaunchTransport} from '@webhands/core';
+
+const transport = new PlaywrightLaunchTransport(
+  {}, // profile location (omit for ~/.webhands)
+  [], // extra hands
+  {stealth: true, systemBrowser: 'chrome'},
+);
+// Stealth + headed + a real logged-in profile is the strongest recipe:
+const session = await transport.open({
+  mode: 'launch',
+  profile: 'default',
+  headed: true,
+});
+```
+
+If stealth is enabled but `patchright` is not installed, the open throws a typed
+`MissingStealthDependencyError` (the CLI prints `pnpm add patchright` as the fix).
+It **never silently falls back** to vanilla Playwright, because that would put
+the tell back without telling you.
+
+**Honest caveat.** Stealth addresses ONLY the CDP `Runtime.enable` automation
+tell. It is **necessary-but-not-sufficient**: IP reputation and session/profile
+reputation still matter. The realistic recipe is stealth +
+`systemBrowser: 'chrome'` + headed + a warmed, logged-in profile + a residential
+IP (see
+[`docs/adr/0002`](docs/adr/0002-real-session-over-fingerprint-spoofing.md)).
+
+## Security note (the `serve` endpoint runs arbitrary code)
+
+The page verbs execute caller-supplied expressions: `eval` runs a JS expression
+in the page, and a `click`/`type` locator is a raw Playwright locator EXPRESSION
+the controller evaluates (see
+[`docs/adr/0004`](docs/adr/0004-verb-surface-exposes-playwright-locator-semantics.md)).
+That is by design for a LOCAL tool driven by its own agent against your own
+session, but it means the running `serve` endpoint is a code-execution surface.
+
+- **Do NOT expose the `serve` endpoint to untrusted callers.** Keep it bound to
+  localhost (the default); never bind it to a public interface or hand its URL to
+  code you do not trust. Anyone who can call it can run arbitrary JavaScript in
+  your logged-in session.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { createCli } from './cli.js';
+/**
+ * The executable entry for the `webhands` binary. It builds the
+ * `incur` CLI (with its default, real-browser session provider) and serves it:
+ * `serve()` parses argv, runs the matched command, writes the structured output
+ * envelope, and handles `--mcp` / `--llms` / `mcp add` / `skills add` for free.
+ *
+ * Kept separate from the builder (`cli.ts`) so tests drive the builder with an
+ * injected provider via `serve(argv, {stdout, exit})` without spawning a real
+ * browser, and only THIS file performs the real `.serve()`.
+ */
+void createCli().serve();
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,SAAS,EAAC,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,KAAK,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,95 @@
+import { Cli } from 'incur';
+import { buildPrompt, resolveProfileLocation, type OpenTarget, type RunningSessionServer } from '@webhands/core';
+import { type SessionProvider } from './session-provider.js';
+import { setupProfile } from '@webhands/core';
+/**
+ * The CLI binary name. Used both as the `incur` CLI name and (echoed back from
+ * `c.name`) inside every fix-command message, so a suggested command always
+ * matches how the user invoked the tool.
+ */
+export declare const CLI_NAME = "webhands";
+/**
+ * The default profile name a page verb / launch / setup-profile targets when
+ * the user does not name one. A single, predictable default keeps the common
+ * case a one-word command; a user with several sessions passes `--profile`.
+ */
+export declare const DEFAULT_PROFILE = "default";
+/** Injectable dependencies, so CLI-level tests exercise the WIRING with no real browser. */
+export interface CliDeps {
+    /**
+     * How a verb command obtains a live session. Defaults to the v1 Playwright
+     * provider; tests inject a stub-backed (or throwing) provider to assert the
+     * envelope/cta/manifest and the typed-error fix messages without a browser.
+     * See {@link SessionProvider}.
+     */
+    readonly sessionProvider?: SessionProvider;
+    /**
+     * The `setup-profile` orchestration (defaults to `core`'s `setupProfile`).
+     * Injectable so the `setup-profile` command's wiring is testable headlessly.
+     */
+    readonly setupProfile?: typeof setupProfile;
+    /** Overrides for the controller home root (tests pass a temp dir). */
+    readonly home?: {
+        root?: string;
+        env?: NodeJS.ProcessEnv;
+    };
+    /**
+     * How the `serve` command brings up the single long-lived session (ADR-0005).
+     * Defaults to {@link startSessionServer} bound to the v1 Playwright transports;
+     * injectable so `serve`/`stop` wiring is testable with a stub transport and no
+     * real browser, and so a test can drive the server lifecycle deterministically.
+     */
+    readonly serveSession?: ServeSession;
+    /**
+     * The version string reported by `--version`, the help header, and the MCP
+     * server. Defaults to {@link VERSION} (this package's `package.json` version);
+     * injectable so a test can assert the wiring deterministically.
+     */
+    readonly version?: string;
+}
+/**
+ * The `serve`-command seam: bring up the ONE long-lived session for a target and
+ * return the running server (its advertised endpoint + an explicit `stop`). The
+ * default wraps `core`'s {@link startSessionServer} with the v1 Playwright
+ * transports; tests inject a stub-backed one.
+ */
+export type ServeSession = (target: OpenTarget, options: {
+    root?: string;
+    env?: NodeJS.ProcessEnv;
+}, launchPolicy?: LaunchPolicy) => Promise<RunningSessionServer>;
+/**
+ * Transport-construction policy for a LAUNCH-mode open: the opt-in stealth
+ * toggle and the optional system browser to drive. Kept SEPARATE from
+ * {@link OpenTarget} so the seam stays free of Playwright/CDP/stealth concepts
+ * (ADR-0003); it rides alongside the target into the transport constructor only.
+ * Ignored for attach (the user's own browser is reused as-is).
+ */
+export interface LaunchPolicy {
+    /** Opt-in Patchright-backed stealth launch. Default off. */
+    readonly stealth?: boolean;
+    /**
+     * Drive a browser already installed on the system (e.g. `'chrome'`) instead
+     * of the bundled Chromium. Omit for bundled Chromium.
+     */
+    readonly systemBrowser?: string;
+}
+/**
+ * Build the `incur` CLI that wraps `core`'s verb surface (PRD Implementation
+ * Decisions — `cli`; stories 12-14, 17).
+ *
+ * Because it is built on `incur`, the SAME binary is also an MCP server
+ * (`--mcp` / `mcp add`) and emits a skills / `--llms` manifest with NO bespoke
+ * MCP code: those come from incur for free. Each command declares zod
+ * `args`/`options`/`output` schemas (so input is validated and output has a
+ * known shape), returns the structured TOON/JSON envelope, and attaches `cta`
+ * next-verb hints. Typed `core` errors (missing binary / missing profile) are
+ * mapped to the user-facing message + exact fix command via
+ * {@link mapControllerError}.
+ *
+ * Returns the built `Cli` WITHOUT calling `.serve()`, so a test can drive it via
+ * `serve(argv, {stdout, exit})` or `cli.fetch(req)` and the bin entry owns the
+ * real `.serve()`.
+ */
+export declare function createCli(deps?: CliDeps): Cli.Cli<{}, undefined, undefined, undefined>;
+export { buildPrompt, resolveProfileLocation };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAC7B,OAAO,EACN,WAAW,EACX,sBAAsB,EAWtB,KAAK,UAAU,EACf,KAAK,oBAAoB,EAKzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAEN,KAAK,eAAe,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAG5C;;;;GAIG;AACH,eAAO,MAAM,QAAQ,aAAa,CAAC;AAMnC;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,4FAA4F;AAC5F,MAAM,WAAW,OAAO;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;KAAC,CAAC;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAC,EACjD,YAAY,CAAC,EAAE,YAAY,KACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAChC;AAwID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,OAAY,gDA+hB3C;AAuED,OAAO,EAAC,WAAW,EAAE,sBAAsB,EAAC,CAAC"}