webhands 0.0.0 → 0.1.6

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+import { MissingBrowserBinaryError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, type ControllerError, type ControllerErrorCode } from '@webhands/core';
+/**
+ * Map a TYPED `core` error condition into the user-facing message + the EXACT
+ * command to fix it (PRD story 17).
+ *
+ * `core` OWNS the typed conditions (a `ControllerError` with a stable `code`,
+ * raised by the transports — see `packages/core/src/errors.ts`); the CLI OWNS
+ * the user-facing message text. The CLI never re-DETECTS a missing binary or a
+ * missing profile (no second `stat`, no message-string match): it branches on
+ * the machine-readable `code` and composes the fix command from the structured
+ * context the error already carries (`browser`, `profile`, `profileDir`, ...).
+ *
+ * The result is fed to incur's `c.error({code, message, ...})` so the failure
+ * surfaces in the structured output envelope with the SAME `code` an agent can
+ * branch on, and a `message` whose final line is a copy-pasteable fix command.
+ */
+export interface MappedError {
+    /** The machine-readable `core` error code, surfaced unchanged to the agent. */
+    readonly code: ControllerErrorCode;
+    /** The full user-facing message, ending in the exact fix command. */
+    readonly message: string;
+}
+/**
+ * Compose the EXACT fix command for a typed `core` error. Returned alongside
+ * the message so a test can assert the precise command, and so the wording
+ * lives in ONE place. `binary` is the CLI binary name (`incur` passes it to the
+ * handler as `c.name`), so the suggested command always matches how the user
+ * invoked the tool.
+ */
+export declare function fixCommandFor(error: ControllerError, binary: string): string;
+/**
+ * If `cause` is a typed `core` error, return the {@link MappedError} (the
+ * user-facing message with the exact fix command appended); otherwise return
+ * `undefined` so the caller falls back to the generic error path.
+ *
+ * The message is the typed error's own message (which already states the
+ * condition in domain terms) followed by a blank line and a `To fix, run:`
+ * block naming the exact command. We keep `core`'s message rather than
+ * re-author it, so the condition text has one source of truth; the CLI's job is
+ * only to ADD the actionable fix command.
+ */
+export declare function mapControllerError(cause: unknown, binary: string): MappedError | undefined;
+export { MissingBrowserBinaryError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, };
+export type { ControllerError, ControllerErrorCode };
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAmC5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACZ,WAAW,GAAG,SAAS,CASzB;AAID,OAAO,EACN,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GACzB,CAAC;AACF,YAAY,EAAC,eAAe,EAAE,mBAAmB,EAAC,CAAC"}

package/dist/errors.js

@@ -0,0 +1,69 @@
+import { isControllerError, MissingBrowserBinaryError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, } from '@webhands/core';
+/**
+ * Compose the EXACT fix command for a typed `core` error. Returned alongside
+ * the message so a test can assert the precise command, and so the wording
+ * lives in ONE place. `binary` is the CLI binary name (`incur` passes it to the
+ * handler as `c.name`), so the suggested command always matches how the user
+ * invoked the tool.
+ */
+export function fixCommandFor(error, binary) {
+    switch (error.code) {
+        case 'missing-browser-binary':
+            // Playwright ships its own browser binaries; `playwright install
+            // <browser>` is the documented way to download the missing one. We name
+            // the specific browser from the typed error rather than a generic hint.
+            return `npx playwright install ${error.browser}`;
+        case 'missing-profile':
+            // A profile is created by the headed `setup-profile` flow (the ONE place
+            // a profile dir is created — see core's MissingProfileError). Name the
+            // profile so the command is ready to run as-is.
+            return `${binary} setup-profile --profile ${error.profile}`;
+        case 'attach-not-chromium':
+            // attach is Chromium-only; the fix is to start Chromium/Chrome with a
+            // remote-debugging port and attach to THAT endpoint.
+            return `${binary} attach --endpoint http://127.0.0.1:9222 (start Chromium/Chrome with --remote-debugging-port=9222 first)`;
+        case 'attach-no-context':
+            // The reached browser has no window/tab to reuse; the fix is to open one.
+            return `${binary} attach --endpoint ${error.endpoint} (open a window/tab in that browser first)`;
+        case 'no-live-server':
+            // No long-lived session server is running (ADR-0005): a verb is a thin
+            // client and has nothing to drive. The fix is to bring one up FIRST with
+            // `serve`; we never auto-spawn a browser in v1.
+            return `${binary} serve`;
+        case 'session-already-active':
+            // A session is already live; v1 holds exactly one. The fix is to tear it
+            // down before starting another.
+            return `${binary} stop`;
+        default: {
+            // Exhaustiveness guard: a new ControllerErrorCode must add a fix command
+            // here rather than silently fall through to a generic message.
+            const _never = error.code;
+            return `Run \`${binary} --help\` (unhandled error code: ${String(_never)}).`;
+        }
+    }
+}
+/**
+ * If `cause` is a typed `core` error, return the {@link MappedError} (the
+ * user-facing message with the exact fix command appended); otherwise return
+ * `undefined` so the caller falls back to the generic error path.
+ *
+ * The message is the typed error's own message (which already states the
+ * condition in domain terms) followed by a blank line and a `To fix, run:`
+ * block naming the exact command. We keep `core`'s message rather than
+ * re-author it, so the condition text has one source of truth; the CLI's job is
+ * only to ADD the actionable fix command.
+ */
+export function mapControllerError(cause, binary) {
+    if (!isControllerError(cause)) {
+        return undefined;
+    }
+    const fix = fixCommandFor(cause, binary);
+    return {
+        code: cause.code,
+        message: `${cause.message}\n\nTo fix, run:\n  ${fix}`,
+    };
+}
+// Re-export the concrete classes so a test importing from the cli package can
+// construct/assert against them without reaching into core directly.
+export { MissingBrowserBinaryError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, };
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAGzB,MAAM,gBAAgB,CAAC;AAwBxB;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAsB,EAAE,MAAc;IACnE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,wBAAwB;YAC5B,iEAAiE;YACjE,wEAAwE;YACxE,wEAAwE;YACxE,OAAO,0BAA2B,KAAmC,CAAC,OAAO,EAAE,CAAC;QACjF,KAAK,iBAAiB;YACrB,yEAAyE;YACzE,uEAAuE;YACvE,gDAAgD;YAChD,OAAO,GAAG,MAAM,4BAA6B,KAA6B,CAAC,OAAO,EAAE,CAAC;QACtF,KAAK,qBAAqB;YACzB,sEAAsE;YACtE,qDAAqD;YACrD,OAAO,GAAG,MAAM,0GAA0G,CAAC;QAC5H,KAAK,mBAAmB;YACvB,0EAA0E;YAC1E,OAAO,GAAG,MAAM,sBAAuB,KAA8B,CAAC,QAAQ,4CAA4C,CAAC;QAC5H,KAAK,gBAAgB;YACpB,uEAAuE;YACvE,yEAAyE;YACzE,gDAAgD;YAChD,OAAO,GAAG,MAAM,QAAQ,CAAC;QAC1B,KAAK,wBAAwB;YAC5B,yEAAyE;YACzE,gCAAgC;YAChC,OAAO,GAAG,MAAM,OAAO,CAAC;QACzB,OAAO,CAAC,CAAC,CAAC;YACT,yEAAyE;YACzE,+DAA+D;YAC/D,MAAM,MAAM,GAAU,KAAK,CAAC,IAAI,CAAC;YACjC,OAAO,SAAS,MAAM,oCAAoC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QAC9E,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CACjC,KAAc,EACd,MAAc;IAEd,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACzC,OAAO;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,uBAAuB,GAAG,EAAE;KACrD,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,qEAAqE;AACrE,OAAO,EACN,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { Driver } from '@webhands/core';
+/**
+ * The `incur`-based CLI wrapper around `core` (the `webhands`
+ * binary). It binds ONE `incur` command per verb (`goto`, `snapshot`, `click`,
+ * `type`, `eval`, `wait`, `cookies`) plus `setup-profile`/`launch`/`attach`,
+ * each with a zod `args`/`options`/`output` schema, returns the structured
+ * TOON/JSON envelope with `cta` next-verb hints, and maps `core`'s typed
+ * missing-binary / missing-profile errors to an actionable fix command.
+ *
+ * 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. The executable entry (`bin.ts`) calls `.serve()`; this module
+ * exports the builder + its types so a test (or a host) can drive the CLI
+ * programmatically (`createCli().serve(argv, {stdout, exit})` / `cli.fetch`).
+ */
+export { createCli, CLI_NAME, DEFAULT_PROFILE, type CliDeps, type ServeSession, } from './cli.js';
+export { createDefaultSessionProvider, type SessionProvider, type DefaultSessionProviderOptions, } from './session-provider.js';
+export { mapControllerError, fixCommandFor, type MappedError } from './errors.js';
+export type { Driver };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACN,SAAS,EACT,QAAQ,EACR,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,YAAY,GACjB,MAAM,UAAU,CAAC;AAElB,OAAO,EACN,4BAA4B,EAC5B,KAAK,eAAe,EACpB,KAAK,6BAA6B,GAClC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAC,kBAAkB,EAAE,aAAa,EAAE,KAAK,WAAW,EAAC,MAAM,aAAa,CAAC;AAIhF,YAAY,EAAC,MAAM,EAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * The `incur`-based CLI wrapper around `core` (the `webhands`
+ * binary). It binds ONE `incur` command per verb (`goto`, `snapshot`, `click`,
+ * `type`, `eval`, `wait`, `cookies`) plus `setup-profile`/`launch`/`attach`,
+ * each with a zod `args`/`options`/`output` schema, returns the structured
+ * TOON/JSON envelope with `cta` next-verb hints, and maps `core`'s typed
+ * missing-binary / missing-profile errors to an actionable fix command.
+ *
+ * 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. The executable entry (`bin.ts`) calls `.serve()`; this module
+ * exports the builder + its types so a test (or a host) can drive the CLI
+ * programmatically (`createCli().serve(argv, {stdout, exit})` / `cli.fetch`).
+ */
+export { createCli, CLI_NAME, DEFAULT_PROFILE, } from './cli.js';
+export { createDefaultSessionProvider, } from './session-provider.js';
+export { mapControllerError, fixCommandFor } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACN,SAAS,EACT,QAAQ,EACR,eAAe,GAGf,MAAM,UAAU,CAAC;AAElB,OAAO,EACN,4BAA4B,GAG5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAC,kBAAkB,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC"}

package/dist/session-provider.d.ts

@@ -0,0 +1,52 @@
+import { type OpenTarget, type Session } from '@webhands/core';
+/**
+ * How a CLI verb command obtains a live {@link Session} to run against.
+ *
+ * This is the ONE seam the verb commands use to reach a browser. It is
+ * deliberately a single function (open a session for an {@link OpenTarget})
+ * rather than the transports directly, for two reasons:
+ *
+ * 1. **Testability of the WIRING.** CLI-level tests assert incur wiring
+ *    (schemas, output envelope, cta, manifest, error text), NOT verb behaviour
+ *    (that is covered at the `core` seam). A test injects a provider backed by
+ *    the `core` `StubTransport`, so the command surface can be exercised with no
+ *    real browser, and a test can inject a provider that THROWS the typed
+ *    `core` errors to assert the actionable fix-command messages.
+ *
+ * 2. **The cross-invocation persistence swap point.** Per ADR-0005 a single
+ *    browser is kept alive between separate CLI invocations behind a long-lived
+ *    `serve` process; verb commands are THIN CLIENTS of that server. The default
+ *    provider (below) is now exactly that thin client: it discovers the running
+ *    server via the endpoint file and returns a {@link connectRemoteSession}
+ *    proxy that drives the server's already-live page; when NO server is live it
+ *    raises a typed {@link NoLiveServerError} so the CLI prints "run `serve`
+ *    first" and exits non-zero, never auto-spawning a browser (ADR-0005:
+ *    lifecycle is EXPLICIT in v1).
+ */
+export type SessionProvider = (target: OpenTarget) => Promise<Session>;
+/** Overrides for where the default provider discovers the running server (tests pass a temp root). */
+export interface DefaultSessionProviderOptions {
+    /** Explicit controller home root. Omit to use `~/.webhands`. */
+    readonly root?: string;
+    /** Environment to read the home override from. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * The v1 default {@link SessionProvider}: a THIN CLIENT of the long-lived
+ * `serve` process (ADR-0005).
+ *
+ * It reads the endpoint file the running server advertised under the config dir
+ * and returns a {@link connectRemoteSession} proxy that forwards each verb to
+ * the server's single live page. There is no per-invocation browser launch
+ * here: a verb invocation drives the SAME live page the server holds, which is
+ * what makes session state persist across separate CLI processes.
+ *
+ * The {@link OpenTarget} is intentionally IGNORED for discovery: which browser
+ * to launch (`launch`/`attach`, the profile) was decided once, by the `serve`
+ * command, when the single session was brought up. A verb does not get to pick
+ * a different browser; it just drives the live one. If no server is live the
+ * provider raises {@link NoLiveServerError} (mapped by the CLI to "run `serve`
+ * first"); it never silently opens a browser.
+ */
+export declare function createDefaultSessionProvider(options?: DefaultSessionProviderOptions): SessionProvider;
+//# sourceMappingURL=session-provider.d.ts.map

package/dist/session-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-provider.d.ts","sourceRoot":"","sources":["../src/session-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvE,sGAAsG;AACtG,MAAM,WAAW,6BAA6B;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,GAAE,6BAAkC,GACzC,eAAe,CAQjB"}

package/dist/session-provider.js

@@ -0,0 +1,28 @@
+import { connectRemoteSession, NoLiveServerError, readSessionEndpoint, } from '@webhands/core';
+/**
+ * The v1 default {@link SessionProvider}: a THIN CLIENT of the long-lived
+ * `serve` process (ADR-0005).
+ *
+ * It reads the endpoint file the running server advertised under the config dir
+ * and returns a {@link connectRemoteSession} proxy that forwards each verb to
+ * the server's single live page. There is no per-invocation browser launch
+ * here: a verb invocation drives the SAME live page the server holds, which is
+ * what makes session state persist across separate CLI processes.
+ *
+ * The {@link OpenTarget} is intentionally IGNORED for discovery: which browser
+ * to launch (`launch`/`attach`, the profile) was decided once, by the `serve`
+ * command, when the single session was brought up. A verb does not get to pick
+ * a different browser; it just drives the live one. If no server is live the
+ * provider raises {@link NoLiveServerError} (mapped by the CLI to "run `serve`
+ * first"); it never silently opens a browser.
+ */
+export function createDefaultSessionProvider(options = {}) {
+    return async (_target) => {
+        const endpoint = await readSessionEndpoint(options);
+        if (endpoint === undefined) {
+            throw new NoLiveServerError();
+        }
+        return connectRemoteSession(endpoint.url);
+    };
+}
+//# sourceMappingURL=session-provider.js.map

package/dist/session-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-provider.js","sourceRoot":"","sources":["../src/session-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,GAGnB,MAAM,gBAAgB,CAAC;AAoCxB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,4BAA4B,CAC3C,UAAyC,EAAE;IAE3C,OAAO,KAAK,EAAE,OAAmB,EAAoB,EAAE;QACtD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,iBAAiB,EAAE,CAAC;QAC/B,CAAC;QACD,OAAO,oBAAoB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC,CAAC;AACH,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The CLI version, read from this package's `package.json` at build time via a
+ * JSON import attribute (`with { type: 'json' }`). Bundled into the emit, so
+ * there is no runtime filesystem read; publish-safe because `dist/version.js`
+ * resolves `../package.json` to the package root, which npm always ships.
+ *
+ * Passed into `Cli.create(..., { version })` so `--version`, the help header,
+ * and the MCP server version all report the real package version.
+ */
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,EAAE,MAAoB,CAAC"}

package/dist/version.js

@@ -0,0 +1,12 @@
+import pkg from '../package.json' with { type: 'json' };
+/**
+ * The CLI version, read from this package's `package.json` at build time via a
+ * JSON import attribute (`with { type: 'json' }`). Bundled into the emit, so
+ * there is no runtime filesystem read; publish-safe because `dist/version.js`
+ * resolves `../package.json` to the package root, which npm always ships.
+ *
+ * Passed into `Cli.create(..., { version })` so `--version`, the help header,
+ * and the MCP server version all report the real package version.
+ */
+export const VERSION = pkg.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAM,IAAI,EAAE,MAAM,EAAC,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC"}

package/package.json

@@ -1,4 +1,60 @@
 {
   "name": "webhands",
-  "version": "0.0.0"
-}
+  "version": "0.1.6",
+  "description": "A CLI (and 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.",
+  "keywords": [
+    "browser",
+    "playwright",
+    "automation",
+    "cli",
+    "mcp",
+    "agent"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "author": "wighawag",
+  "homepage": "https://github.com/wighawag/webhands#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wighawag/webhands.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/wighawag/webhands/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "webhands": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "incur": "^0.4.10",
+    "@webhands/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "as-soon": "^0.1.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "as-soon -w src pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/bin.ts

@@ -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();