@mochi.js/core 0.0.1 → 0.1.2

package/src/__tests__/proxy-auth.test.ts

@@ -0,0 +1,253 @@
+/**
+ * Unit tests for `parseProxyUrl` + `installProxyAuth`.
+ *
+ * `parseProxyUrl`: pure function — exercises HTTP/HTTPS/SOCKS5/SOCKS4 ×
+ * with-auth/no-auth × edge cases (missing port, IPv6 host, percent-encoded
+ * creds, empty password).
+ *
+ * `installProxyAuth`: drives a fake CDP router. Verifies:
+ *   - `Fetch.enable` is sent with `handleAuthRequests: true, patterns: [{ urlPattern: "*" }]`.
+ *   - `Fetch.authRequired` events trigger `Fetch.continueWithAuth` carrying
+ *     the configured creds.
+ *   - The defensive `Fetch.requestPaused` handler issues `Fetch.continueRequest`.
+ *   - `dispose()` sends `Fetch.disable` and is idempotent.
+ *
+ * @see tasks/0160-proxy-auth-and-ci-fix.md
+ */
+
+import { describe, expect, it } from "bun:test";
+import { MessageRouter } from "../cdp/router";
+import type { PipeReader, PipeWriter } from "../cdp/transport";
+import { installProxyAuth, parseProxyUrl } from "../proxy-auth";
+
+describe("parseProxyUrl", () => {
+  it("HTTP with user:pass — splits server + auth", () => {
+    expect(parseProxyUrl("http://user:pass@host.example:8080")).toEqual({
+      server: "http://host.example:8080",
+      auth: { username: "user", password: "pass" },
+      protocol: "http",
+    });
+  });
+
+  it("HTTPS with user:pass", () => {
+    expect(parseProxyUrl("https://u:p@proxy.tld:443")).toEqual({
+      server: "https://proxy.tld:443",
+      auth: { username: "u", password: "p" },
+      protocol: "https",
+    });
+  });
+
+  it("SOCKS5 with user:pass", () => {
+    expect(parseProxyUrl("socks5://u:p@socks.example:1080")).toEqual({
+      server: "socks5://socks.example:1080",
+      auth: { username: "u", password: "p" },
+      protocol: "socks5",
+    });
+  });
+
+  it("SOCKS4 with user (no pass) — password is empty string, not undefined", () => {
+    expect(parseProxyUrl("socks4://lone@socks.example:1080")).toEqual({
+      server: "socks4://socks.example:1080",
+      auth: { username: "lone", password: "" },
+      protocol: "socks4",
+    });
+  });
+
+  it("SOCKS5 with user only — empty password", () => {
+    expect(parseProxyUrl("socks5://lone@socks.example:1080")).toEqual({
+      server: "socks5://socks.example:1080",
+      auth: { username: "lone", password: "" },
+      protocol: "socks5",
+    });
+  });
+
+  it("HTTP with no auth — auth is undefined", () => {
+    const out = parseProxyUrl("http://host.example:8080");
+    expect(out.server).toBe("http://host.example:8080");
+    expect(out.auth).toBeUndefined();
+    expect(out.protocol).toBe("http");
+  });
+
+  it("percent-encoded creds round-trip decoded", () => {
+    expect(parseProxyUrl("http://user%40domain:p%40ss@host.example:8080")).toEqual({
+      server: "http://host.example:8080",
+      auth: { username: "user@domain", password: "p@ss" },
+      protocol: "http",
+    });
+  });
+
+  it("colon in encoded password decodes", () => {
+    expect(parseProxyUrl("http://u:p%3Aass@host:8080")).toEqual({
+      server: "http://host:8080",
+      auth: { username: "u", password: "p:ass" },
+      protocol: "http",
+    });
+  });
+
+  it("IPv6 host with brackets — preserved in server URL", () => {
+    expect(parseProxyUrl("http://user:pass@[::1]:8080")).toEqual({
+      server: "http://[::1]:8080",
+      auth: { username: "user", password: "pass" },
+      protocol: "http",
+    });
+  });
+
+  it("IPv6 host without auth", () => {
+    const out = parseProxyUrl("http://[2001:db8::1]:8080");
+    expect(out.server).toBe("http://[2001:db8::1]:8080");
+    expect(out.auth).toBeUndefined();
+  });
+
+  it("missing port — applies protocol default (HTTP=80)", () => {
+    expect(parseProxyUrl("http://host.example").server).toBe("http://host.example:80");
+  });
+
+  it("missing port — applies protocol default (HTTPS=443)", () => {
+    expect(parseProxyUrl("https://host.example").server).toBe("https://host.example:443");
+  });
+
+  it("missing port — applies protocol default (SOCKS5=1080)", () => {
+    expect(parseProxyUrl("socks5://host.example").server).toBe("socks5://host.example:1080");
+  });
+
+  it("missing port — applies protocol default (SOCKS4=1080)", () => {
+    expect(parseProxyUrl("socks4://host.example").server).toBe("socks4://host.example:1080");
+  });
+
+  it("rejects unsupported protocol", () => {
+    expect(() => parseProxyUrl("ftp://host:21")).toThrow(/unsupported proxy protocol/);
+  });
+
+  it("rejects malformed URL", () => {
+    expect(() => parseProxyUrl("not a url")).toThrow(/invalid proxy URL/);
+  });
+
+  it("uppercase protocol normalizes to lowercase", () => {
+    expect(parseProxyUrl("HTTP://host.example:8080").protocol).toBe("http");
+  });
+});
+
+// ---- installProxyAuth -------------------------------------------------------
+
+interface FakeRouter {
+  router: MessageRouter;
+  written: { method: string; params?: unknown }[];
+  pushEvent(method: string, params: unknown): void;
+}
+
+function makeRouter(): FakeRouter {
+  const written: { method: string; params?: unknown }[] = [];
+  let pumpController: ReadableStreamDefaultController<Uint8Array> | null = null;
+  const stream = new ReadableStream<Uint8Array>({
+    start(c) {
+      pumpController = c;
+    },
+  });
+  const reader: PipeReader = {
+    getReader: () => stream.getReader(),
+  };
+  const writer: PipeWriter = {
+    write: (chunk: Uint8Array) => {
+      const last = chunk[chunk.length - 1] === 0 ? chunk.length - 1 : chunk.length;
+      const json = new TextDecoder().decode(chunk.subarray(0, last));
+      try {
+        const obj = JSON.parse(json) as { id?: number; method: string; params?: unknown };
+        written.push({ method: obj.method, params: obj.params });
+        // Auto-resolve the request immediately so the await in
+        // `installProxyAuth` doesn't hang.
+        if (typeof obj.id === "number") {
+          const reply = JSON.stringify({ id: obj.id, result: {} });
+          const enc = new TextEncoder().encode(reply);
+          const out = new Uint8Array(enc.length + 1);
+          out.set(enc, 0);
+          out[enc.length] = 0;
+          pumpController?.enqueue(out);
+        }
+      } catch {
+        // ignore
+      }
+      return chunk.byteLength;
+    },
+    flush: () => undefined,
+    end: () => undefined,
+  };
+  const router = new MessageRouter(reader, writer);
+  router.start();
+  const enc = new TextEncoder();
+  return {
+    router,
+    written,
+    pushEvent(method: string, params: unknown): void {
+      const bytes = enc.encode(JSON.stringify({ method, params }));
+      const out = new Uint8Array(bytes.length + 1);
+      out.set(bytes, 0);
+      out[bytes.length] = 0;
+      pumpController?.enqueue(out);
+    },
+  };
+}
+
+describe("installProxyAuth", () => {
+  it("sends Fetch.enable with handleAuthRequests:true and empty patterns", async () => {
+    const f = makeRouter();
+    const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
+    const enable = f.written.find((c) => c.method === "Fetch.enable");
+    expect(enable).toBeDefined();
+    expect(enable?.params).toEqual({ handleAuthRequests: true, patterns: [{ urlPattern: "*" }] });
+    await handle.dispose();
+    await f.router.close();
+  });
+
+  it("answers Fetch.authRequired with Fetch.continueWithAuth(ProvideCredentials)", async () => {
+    const f = makeRouter();
+    const handle = await installProxyAuth(f.router, { username: "alice", password: "s3cret" });
+    f.pushEvent("Fetch.authRequired", { requestId: "req-42", authChallenge: { source: "Proxy" } });
+    // Allow microtasks + the writer push to flush.
+    await new Promise((r) => setTimeout(r, 10));
+    const reply = f.written.find((c) => c.method === "Fetch.continueWithAuth");
+    expect(reply).toBeDefined();
+    expect(reply?.params).toEqual({
+      requestId: "req-42",
+      authChallengeResponse: {
+        response: "ProvideCredentials",
+        username: "alice",
+        password: "s3cret",
+      },
+    });
+    await handle.dispose();
+    await f.router.close();
+  });
+
+  it("forwards Fetch.requestPaused via Fetch.continueRequest (defensive handler)", async () => {
+    const f = makeRouter();
+    const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
+    f.pushEvent("Fetch.requestPaused", { requestId: "rp-1" });
+    await new Promise((r) => setTimeout(r, 10));
+    const reply = f.written.find((c) => c.method === "Fetch.continueRequest");
+    expect(reply).toBeDefined();
+    expect(reply?.params).toEqual({ requestId: "rp-1" });
+    await handle.dispose();
+    await f.router.close();
+  });
+
+  it("dispose() sends Fetch.disable and is idempotent", async () => {
+    const f = makeRouter();
+    const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
+    await handle.dispose();
+    await handle.dispose();
+    const disables = f.written.filter((c) => c.method === "Fetch.disable");
+    expect(disables.length).toBe(1);
+    await f.router.close();
+  });
+
+  it("after dispose, further authRequired events do not produce continueWithAuth", async () => {
+    const f = makeRouter();
+    const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
+    await handle.dispose();
+    f.pushEvent("Fetch.authRequired", { requestId: "late" });
+    await new Promise((r) => setTimeout(r, 10));
+    const replies = f.written.filter((c) => c.method === "Fetch.continueWithAuth");
+    expect(replies.length).toBe(0);
+    await f.router.close();
+  });
+});

package/src/__tests__/router.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Unit tests for `MessageRouter`. Use a fake transport (no Bun.spawn / no
+ * Chromium) — we simulate inbound frames by calling the listener directly.
+ *
+ * Coverage targets:
+ *   - request/response correlation by id
+ *   - error responses surface as CdpRemoteError
+ *   - timeouts surface as CdpTimeoutError
+ *   - event subscriptions: on, once, off
+ *   - close rejects pending calls with BrowserCrashedError
+ *   - ForbiddenCdpMethodError surfaces synchronously through `.send()`
+ */
+
+import { describe, expect, it } from "bun:test";
+import { ForbiddenCdpMethodError } from "../cdp/forbidden";
+import { BrowserCrashedError, CdpRemoteError, CdpTimeoutError, MessageRouter } from "../cdp/router";
+import type { PipeReader, PipeWriter } from "../cdp/transport";
+
+interface FakeTransport {
+  router: MessageRouter;
+  /** All bytes the router has written, decoded as JSON-RPC objects. */
+  written: unknown[];
+  /** Inject one inbound JSON frame (router parses + dispatches). */
+  push(json: unknown): void;
+  /** Simulate browser exit / pipe close. */
+  closeFromBrowser(reason?: Error): Promise<void>;
+}
+
+function makeRouter(opts: { defaultTimeoutMs?: number } = {}): FakeTransport {
+  const written: unknown[] = [];
+  // The fake reader never produces data on its own — we drive the router by
+  // calling the framer-bypass pathway via the transport's onFrame listener.
+  // To do that we re-construct: keep a reference to the listener, then create
+  // the router with a stream that we control.
+  let pumpController: ReadableStreamDefaultController<Uint8Array> | null = null;
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      pumpController = controller;
+    },
+  });
+  const reader: PipeReader = {
+    getReader: () => stream.getReader(),
+  };
+  const writer: PipeWriter = {
+    write: (chunk) => {
+      // Strip trailing NUL and decode.
+      const u8 = chunk;
+      const last = u8[u8.length - 1] === 0 ? u8.length - 1 : u8.length;
+      const json = new TextDecoder().decode(u8.subarray(0, last));
+      try {
+        written.push(JSON.parse(json));
+      } catch {
+        written.push(json);
+      }
+    },
+    flush: () => undefined,
+    end: () => undefined,
+  };
+  const router = new MessageRouter(reader, writer, opts);
+  router.start();
+  const enc = new TextEncoder();
+  return {
+    router,
+    written,
+    push(obj: unknown) {
+      const bytes = enc.encode(JSON.stringify(obj));
+      const out = new Uint8Array(bytes.length + 1);
+      out.set(bytes, 0);
+      out[bytes.length] = 0;
+      pumpController?.enqueue(out);
+    },
+    async closeFromBrowser(reason?: Error) {
+      pumpController?.close();
+      await router.close(reason);
+    },
+  };
+}
+
+describe("MessageRouter", () => {
+  it("correlates a response by id and resolves with `result`", async () => {
+    const t = makeRouter();
+    const p = t.router.send<{ ok: true }>("Page.enable");
+    // The router assigned id=1 (first send).
+    t.push({ id: 1, result: { ok: true } });
+    const result = await p;
+    expect(result).toEqual({ ok: true });
+    expect((t.written[0] as { method: string }).method).toBe("Page.enable");
+    await t.closeFromBrowser();
+  });
+
+  it("rejects with CdpRemoteError on a CDP error response", async () => {
+    const t = makeRouter();
+    const p = t.router.send("Page.navigate", { url: "bad" });
+    t.push({ id: 1, error: { code: -32000, message: "Cannot navigate" } });
+    let caught: unknown;
+    try {
+      await p;
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CdpRemoteError);
+    expect((caught as CdpRemoteError).method).toBe("Page.navigate");
+    expect((caught as CdpRemoteError).code).toBe(-32000);
+    await t.closeFromBrowser();
+  });
+
+  it("rejects with CdpTimeoutError after the deadline", async () => {
+    const t = makeRouter({ defaultTimeoutMs: 50 });
+    let caught: unknown;
+    try {
+      await t.router.send("Slow.method");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CdpTimeoutError);
+    expect((caught as CdpTimeoutError).method).toBe("Slow.method");
+    await t.closeFromBrowser();
+  });
+
+  it("dispatches events to on() handlers; supports unsubscribe", async () => {
+    const t = makeRouter();
+    const seen: unknown[] = [];
+    const off = t.router.on("Page.frameNavigated", (params) => seen.push(params));
+    t.push({ method: "Page.frameNavigated", params: { frame: { id: "f1" } } });
+    t.push({ method: "Page.frameNavigated", params: { frame: { id: "f2" } } });
+    await new Promise<void>((r) => setTimeout(r, 5));
+    off();
+    t.push({ method: "Page.frameNavigated", params: { frame: { id: "f3" } } });
+    await new Promise<void>((r) => setTimeout(r, 5));
+    expect(seen).toHaveLength(2);
+    await t.closeFromBrowser();
+  });
+
+  it("once() handlers fire exactly once", async () => {
+    const t = makeRouter();
+    let count = 0;
+    t.router.once("Page.loadEventFired", () => {
+      count++;
+    });
+    t.push({ method: "Page.loadEventFired", params: {} });
+    t.push({ method: "Page.loadEventFired", params: {} });
+    await new Promise<void>((r) => setTimeout(r, 5));
+    expect(count).toBe(1);
+    await t.closeFromBrowser();
+  });
+
+  it("rejects pending calls with BrowserCrashedError when transport closes", async () => {
+    const t = makeRouter();
+    const p = t.router.send("Page.enable");
+    await t.closeFromBrowser();
+    let caught: unknown;
+    try {
+      await p;
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(BrowserCrashedError);
+  });
+
+  it("forbidden methods reject through .send() with ForbiddenCdpMethodError", async () => {
+    const t = makeRouter();
+    let caught: unknown;
+    try {
+      await t.router.send("Runtime.enable");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(ForbiddenCdpMethodError);
+
+    let caught2: unknown;
+    try {
+      await t.router.send("Page.createIsolatedWorld", { frameId: "x" });
+    } catch (err) {
+      caught2 = err;
+    }
+    expect(caught2).toBeInstanceOf(ForbiddenCdpMethodError);
+
+    let caught3: unknown;
+    try {
+      await t.router.send("Runtime.evaluate", {
+        expression: "1+1",
+        includeCommandLineAPI: true,
+      });
+    } catch (err) {
+      caught3 = err;
+    }
+    expect(caught3).toBeInstanceOf(ForbiddenCdpMethodError);
+
+    // None of those should have actually written anything to the transport.
+    expect(t.written).toEqual([]);
+    await t.closeFromBrowser();
+  });
+});

package/src/__tests__/smoke.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "bun:test";
-import { mochi, NotImplementedError, VERSION } from "../index";
+import { mochi, NotImplementedError, Session, VERSION } from "../index";
 
-describe("@mochi.js/core (claim release)", () => {
+describe("@mochi.js/core (phase 0.1)", () => {
   it("exports a VERSION string", () => {
     expect(typeof VERSION).toBe("string");
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
@@ -13,8 +13,14 @@ describe("@mochi.js/core (claim release)", () => {
     expect(mochi.version).toBe(VERSION);
   });
 
-  it("mochi.launch throws NotImplementedError until phase 0.1", () => {
-    expect(() => mochi.launch()).toThrow(NotImplementedError);
-    expect(() => mochi.launch()).toThrow(/not yet implemented/);
+  it("re-exports the Session class as a constructor", () => {
+    expect(typeof Session).toBe("function");
+  });
+
+  it("exports NotImplementedError for placeholder surfaces", () => {
+    const err = new NotImplementedError("page.humanClick");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("NotImplementedError");
+    expect(err.api).toBe("page.humanClick");
   });
 });

package/src/binary.ts

@@ -0,0 +1,129 @@
+/**
+ * Chromium binary resolution.
+ *
+ * Resolution order (per task brief 0011):
+ *   1. `LaunchOptions.binary` (explicit override)
+ *   2. `process.env.MOCHI_CHROMIUM_PATH`
+ *   3. `@mochi.js/cli`'s `resolveChromiumBinary()` if installed
+ *   4. error with actionable message
+ *
+ * The cli import is dynamic + lazy; absence of `@mochi.js/cli` (or absence of
+ * the `resolveChromiumBinary` export — it lands in task 0010) is non-fatal.
+ *
+ * @see PLAN.md §5.1 / §8 / §15
+ */
+
+/**
+ * Thrown when no Chromium binary can be found via any resolution path.
+ * The message names the exact remediation steps.
+ */
+export class ChromiumNotFoundError extends Error {
+  constructor() {
+    super(
+      "[mochi] could not locate a Chromium binary.\n" +
+        "  Resolution order: LaunchOptions.binary > MOCHI_CHROMIUM_PATH env > @mochi.js/cli " +
+        "resolveChromiumBinary().\n" +
+        "  Fix: either\n" +
+        "    • install Chromium-for-Testing via `mochi browsers install` (lands in phase 0.11), or\n" +
+        "    • set MOCHI_CHROMIUM_PATH to a stock Chromium binary, or\n" +
+        '    • pass `binary: "/path/to/chromium"` to mochi.launch().',
+    );
+    this.name = "ChromiumNotFoundError";
+  }
+}
+
+/**
+ * The shape `@mochi.js/cli`'s `resolveChromiumBinary` returns (per task 0010).
+ * Defined inline so we don't take a hard dep on the cli package's type surface.
+ *
+ * The function returns `{ path, channel, version, platform }` on success; it
+ * THROWS when no install is found (with a friendly "run `mochi browsers
+ * install`" message). We wrap in try/catch and treat both throw + missing
+ * symbol as "not resolvable from cli", letting the caller surface the
+ * canonical {@link ChromiumNotFoundError}.
+ *
+ * Earlier versions of this binding incorrectly typed the return as
+ * `string | null` and discarded the resolved object — the integration broke
+ * silently on every host where MOCHI_CHROMIUM_PATH wasn't set (local M4 with
+ * the env var set masked it; CI without it caught it). Pinned by
+ * `tests/contract/core-cli-binary-resolution.contract.test.ts`.
+ */
+type CliResolveResult = {
+  readonly path: string;
+  readonly channel?: string;
+  readonly version?: string;
+  readonly platform?: string;
+};
+type CliResolveFn = (
+  opts?: Record<string, unknown>,
+) => Promise<CliResolveResult> | CliResolveResult;
+
+async function tryCliResolve(): Promise<string | null> {
+  try {
+    // @mochi.js/cli is a lazy, optional dependency at v0.1: task 0010 hasn't
+    // necessarily landed in every consumer's lockfile, and `resolveChromiumBinary`
+    // is a forward-looking export. Importing dynamically + catching keeps the
+    // env-var path working when the cli isn't installed.
+    // @ts-expect-error — optional peer; resolved at runtime if present.
+    const mod = (await import("@mochi.js/cli")) as Record<string, unknown>;
+    const fn = mod.resolveChromiumBinary;
+    if (typeof fn !== "function") return null;
+    const result = await (fn as CliResolveFn)();
+    if (
+      result !== null &&
+      typeof result === "object" &&
+      typeof result.path === "string" &&
+      result.path.length > 0
+    ) {
+      return result.path;
+    }
+    return null;
+  } catch {
+    // cli not installed, the symbol's not exported yet, OR resolveChromiumBinary
+    // threw because no install is registered — all flow to the canonical
+    // ChromiumNotFoundError below. The thrown error from the cli is
+    // intentionally NOT propagated — the core's error message is more
+    // actionable in this layer.
+    return null;
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    return await Bun.file(path).exists();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a Chromium binary path. Returns the first working candidate; throws
+ * {@link ChromiumNotFoundError} if every option is empty.
+ *
+ * @param explicit `LaunchOptions.binary` from the user, if any.
+ */
+export async function resolveBinary(explicit?: string): Promise<string> {
+  if (explicit !== undefined && explicit.length > 0) {
+    if (!(await pathExists(explicit))) {
+      throw new Error(`[mochi] LaunchOptions.binary points to a non-existent path: ${explicit}`);
+    }
+    return explicit;
+  }
+  const fromEnv = process.env.MOCHI_CHROMIUM_PATH;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (!(await pathExists(fromEnv))) {
+      throw new Error(`[mochi] MOCHI_CHROMIUM_PATH points to a non-existent path: ${fromEnv}`);
+    }
+    return fromEnv;
+  }
+  const fromCli = await tryCliResolve();
+  if (fromCli !== null) {
+    if (!(await pathExists(fromCli))) {
+      throw new Error(
+        `[mochi] @mochi.js/cli resolveChromiumBinary returned a non-existent path: ${fromCli}`,
+      );
+    }
+    return fromCli;
+  }
+  throw new ChromiumNotFoundError();
+}