webhands 0.0.0 → 0.1.7

package/src/errors.ts

@@ -0,0 +1,121 @@
+import {
+	isControllerError,
+	MissingBrowserBinaryError,
+	MissingStealthDependencyError,
+	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 function fixCommandFor(error: ControllerError, binary: string): string {
+	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 as MissingBrowserBinaryError).browser}`;
+		case 'missing-stealth-dependency':
+			// Stealth launch was opted into but the OPTIONAL `patchright` dependency
+			// is absent. Name the package from the typed error so the install command
+			// is ready to run; we never silently fall back to vanilla Playwright.
+			return `pnpm add ${(error as MissingStealthDependencyError).dependency}`;
+		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 as MissingProfileError).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 as AttachNoContextError).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: 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: unknown,
+	binary: string,
+): MappedError | undefined {
+	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,
+	MissingStealthDependencyError,
+	MissingProfileError,
+	AttachNotChromiumError,
+	AttachNoContextError,
+	NoLiveServerError,
+	SessionAlreadyActiveError,
+};
+export type {ControllerError, ControllerErrorCode};

package/src/index.ts

@@ -0,0 +1,37 @@
+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 LaunchPolicy,
+	type ServeSession,
+} from './cli.js';
+
+export {
+	createDefaultSessionProvider,
+	type SessionProvider,
+	type DefaultSessionProviderOptions,
+} from './session-provider.js';
+
+export {mapControllerError, fixCommandFor, type MappedError} from './errors.js';
+
+// Re-export the `core` `Driver` seam type so the boundary stays visible from
+// the cli package (it was anchored here by the scaffold).
+export type {Driver};

package/src/session-provider.ts

@@ -0,0 +1,70 @@
+import {
+	connectRemoteSession,
+	NoLiveServerError,
+	readSessionEndpoint,
+	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 function createDefaultSessionProvider(
+	options: DefaultSessionProviderOptions = {},
+): SessionProvider {
+	return async (_target: OpenTarget): Promise<Session> => {
+		const endpoint = await readSessionEndpoint(options);
+		if (endpoint === undefined) {
+			throw new NoLiveServerError();
+		}
+		return connectRemoteSession(endpoint.url);
+	};
+}

package/src/version.ts

@@ -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: string = pkg.version;