npm - @mochi.js/core - Versions diffs - 0.0.1 → 0.1.2 - Mend

@mochi.js/core 0.0.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/README.md +3 -3
package/package.json +11 -4
package/src/__tests__/behavioral.e2e.test.ts +200 -0
package/src/__tests__/binary.test.ts +89 -0
package/src/__tests__/forbidden.test.ts +80 -0
package/src/__tests__/framer.test.ts +92 -0
package/src/__tests__/inject.e2e.test.ts +253 -0
package/src/__tests__/inject.test.ts +276 -0
package/src/__tests__/integration.e2e.test.ts +60 -0
package/src/__tests__/proxy-auth.test.ts +253 -0
package/src/__tests__/router.test.ts +193 -0
package/src/__tests__/smoke.test.ts +11 -5
package/src/binary.ts +129 -0
package/src/cdp/forbidden.ts +102 -0
package/src/cdp/framer.ts +79 -0
package/src/cdp/router.ts +240 -0
package/src/cdp/transport.ts +167 -0
package/src/cdp/types.ts +152 -0
package/src/errors.ts +23 -0
package/src/index.ts +46 -39
package/src/launch.ts +282 -0
package/src/page.ts +979 -0
package/src/proc.ts +213 -0
package/src/proxy-auth.ts +252 -0
package/src/session.ts +638 -0
package/src/version.ts +2 -0

package/README.md CHANGED Viewed

@@ -48,6 +48,6 @@ MIT.
 ## See also
-- [Repo](https://github.com/0xchasercat/mochi.js)
-- [PLAN.md](https://github.com/0xchasercat/mochi.js/blob/main/PLAN.md) — the full design contract
-- [Limits](https://github.com/0xchasercat/mochi.js/blob/main/docs/limits.md) — what the JS-only ceiling honestly does and doesn't cover
+- [Repo](https://github.com/0xchasercat/mochi)
+- [PLAN.md](https://github.com/0xchasercat/mochi/blob/main/PLAN.md) — the full design contract
+- [Limits](https://github.com/0xchasercat/mochi/blob/main/docs/limits.md) — what the JS-only ceiling honestly does and doesn't cover

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mochi.js/core",
-  "version": "0.0.1",
+  "version": "0.1.2",
   "description": "Bun-native browser automation framework — relational fingerprint locking, zero-jitter injection, behavioral playback. The primary entry point.",
   "license": "MIT",
   "type": "module",
@@ -21,14 +21,14 @@
   "engines": {
     "bun": ">=1.1"
   },
-  "homepage": "https://github.com/0xchasercat/mochi.js",
+  "homepage": "https://github.com/0xchasercat/mochi",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/0xchasercat/mochi.js.git",
+    "url": "git+https://github.com/0xchasercat/mochi.git",
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/0xchasercat/mochi.js/issues"
+    "url": "https://github.com/0xchasercat/mochi/issues"
   },
   "keywords": [
     "browser",
@@ -48,6 +48,13 @@
     "lint": "biome check src/",
     "build": "echo 'no build step yet — Bun consumes src/ directly'"
   },
+  "dependencies": {
+    "@mochi.js/behavioral": "^0.1.1",
+    "@mochi.js/challenges": "^0.2.0",
+    "@mochi.js/consistency": "^0.1.0",
+    "@mochi.js/inject": "^0.1.1",
+    "@mochi.js/net": "^0.1.1"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/__tests__/behavioral.e2e.test.ts ADDED Viewed

@@ -0,0 +1,200 @@
+/**
+ * E2E test for the behavioral surface against real Chromium.
+ *
+ * Gated by `MOCHI_E2E=1`. Set `MOCHI_CHROMIUM_PATH` to point at a Chrome /
+ * Chromium-for-Testing binary. Budget: < 15 seconds total.
+ *
+ * Asserts:
+ *   - `humanClick` emits a sequence of `mousemove` events the page sees
+ *     (count > 5 — confirms it's a trajectory, not a single warp).
+ *   - `mousemove` timestamps are monotonic and span a non-trivial range
+ *     (confirms the dispatch layer paces events, not all at t=0).
+ *   - The final mousedown / mouseup land on the target element.
+ *   - `humanType` produces `keydown`/`keyup` for each character (plus the
+ *     mistake/correction events when forced).
+ *   - `humanScroll` advances `window.scrollY` toward the target.
+ *
+ * @see PLAN.md §11
+ * @see tasks/0080-behavioral-engine-v0.md §"Tests"
+ */
+import { describe, expect, it } from "bun:test";
+import { mochi } from "../index";
+const E2E_ENABLED = process.env.MOCHI_E2E === "1";
+const TEST_TIMEOUT_MS = 20_000;
+const describeOrSkip = E2E_ENABLED ? describe : describe.skip;
+const BUTTON_HARNESS_HTML =
+  "data:text/html," +
+  encodeURIComponent(`
+    <!doctype html>
+    <html><head><title>behavioral-e2e</title></head>
+    <body style="margin:0;padding:0;height:2400px;">
+      <div id="filler" style="height:1000px;background:#eef;"></div>
+      <button id="b" style="position:absolute;left:200px;top:150px;width:100px;height:40px;">click me</button>
+      <input id="i" style="position:absolute;left:50px;top:60px;width:200px;height:30px;font-size:16px;" />
+      <div id="footer" style="height:200px;background:#fee;"></div>
+      <script>
+        window.__events = { mousemove: [], mousedown: [], mouseup: [], keydown: [], keyup: [] };
+        for (const t of ["mousemove","mousedown","mouseup"]) {
+          document.addEventListener(t, (e) => {
+            window.__events[t].push({ t: performance.now(), x: e.clientX, y: e.clientY, target: e.target && e.target.id });
+          }, true);
+        }
+        for (const t of ["keydown","keyup"]) {
+          document.addEventListener(t, (e) => {
+            window.__events[t].push({ t: performance.now(), key: e.key });
+          }, true);
+        }
+      </script>
+    </body></html>
+  `);
+describeOrSkip("@mochi.js/core — behavioral E2E (MOCHI_E2E=1)", () => {
+  it(
+    "humanClick produces a trajectory of >5 mousemoves and a final click on the target",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test-behavioral",
+        seed: "e2e-click",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        await page.goto(BUTTON_HARNESS_HTML);
+        await page.humanClick("#b", { preMoveSettle: false });
+        const events = (await page.evaluate(
+          // The function runs as a method on `document` (PLAN.md §8.3 path
+          // through `Runtime.callFunctionOn`); `this.defaultView` reaches
+          // window. We wrote the harness HTML to stash event records on
+          // `window.__events`. Cast via `unknown` so the `this` type fudge
+          // in the page-side closure doesn't trip the strict `any` check.
+          function (this: Document) {
+            const w = this.defaultView as unknown as { __events: unknown };
+            return w?.__events;
+          } as () => unknown,
+        )) as {
+          mousemove: { t: number; x: number; y: number; target: string }[];
+          mousedown: { t: number; x: number; y: number; target: string }[];
+          mouseup: { t: number; x: number; y: number; target: string }[];
+          keydown: { t: number; key: string }[];
+          keyup: { t: number; key: string }[];
+        };
+        expect(events).toBeDefined();
+        expect(events.mousemove.length).toBeGreaterThan(5);
+        // Monotonic timestamps; non-trivial timespan.
+        for (let i = 1; i < events.mousemove.length; i++) {
+          const prev = events.mousemove[i - 1];
+          const cur = events.mousemove[i];
+          if (prev !== undefined && cur !== undefined) {
+            expect(cur.t).toBeGreaterThanOrEqual(prev.t);
+          }
+        }
+        const first = events.mousemove[0];
+        const last = events.mousemove[events.mousemove.length - 1];
+        if (first !== undefined && last !== undefined) {
+          expect(last.t - first.t).toBeGreaterThan(50);
+        }
+        // Final mousedown and mouseup land on (or inside) the button.
+        expect(events.mousedown.length).toBe(1);
+        expect(events.mouseup.length).toBe(1);
+        const md = events.mousedown[0];
+        expect(md?.target).toBe("b");
+        // Surface event counts to the test runner so the orchestrator can
+        // confirm the trajectory shape from CI logs. `console.warn` rather
+        // than `console.log` because the project's biome rule forbids the
+        // latter.
+        console.warn(
+          `[e2e] humanClick: ${events.mousemove.length} moves; mousedown target=${md?.target}; ` +
+            `dt=${last && first ? Math.round(last.t - first.t) : 0} ms`,
+        );
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+  it(
+    "humanType emits keydown/keyup pairs for each character",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test-behavioral",
+        seed: "e2e-type",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        await page.goto(BUTTON_HARNESS_HTML);
+        await page.humanType("#i", "hi", { mistakeRate: 0 });
+        const events = (await page.evaluate(function (this: Document) {
+          const w = this.defaultView as unknown as { __events: unknown };
+          return w?.__events;
+        } as () => unknown)) as {
+          mousemove: { t: number; x: number; y: number }[];
+          mousedown: { t: number; x: number; y: number }[];
+          mouseup: { t: number; x: number; y: number }[];
+          keydown: { t: number; key: string }[];
+          keyup: { t: number; key: string }[];
+        };
+        expect(events.keydown.length).toBe(2);
+        expect(events.keyup.length).toBe(2);
+        expect(events.keydown.map((e) => e.key)).toEqual(["h", "i"]);
+        // Inter-key timing > 0.
+        if (events.keydown.length === 2) {
+          const k0 = events.keydown[0];
+          const k1 = events.keydown[1];
+          if (k0 !== undefined && k1 !== undefined) {
+            expect(k1.t).toBeGreaterThan(k0.t);
+          }
+        }
+        // Surface event counts to the test runner so the orchestrator can
+        // confirm the trajectory shape from CI logs. `console.warn` rather
+        // than `console.log` because the project's biome rule forbids the
+        // latter.
+        console.warn(
+          `[e2e] humanType: keydown.length=${events.keydown.length}, ` +
+            `keys=${events.keydown.map((e) => e.key).join(",")}`,
+        );
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+  it(
+    "humanScroll moves window.scrollY toward the target",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test-behavioral",
+        seed: "e2e-scroll",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        await page.goto(BUTTON_HARNESS_HTML);
+        const before = (await page.evaluate(function (this: Document) {
+          return this.defaultView?.scrollY ?? 0;
+        } as () => unknown)) as number;
+        await page.humanScroll({ to: { x: 0, y: 500 } });
+        const after = (await page.evaluate(function (this: Document) {
+          return this.defaultView?.scrollY ?? 0;
+        } as () => unknown)) as number;
+        expect(after).toBeGreaterThan(before);
+        // Surface event counts to the test runner so the orchestrator can
+        // confirm the trajectory shape from CI logs. `console.warn` rather
+        // than `console.log` because the project's biome rule forbids the
+        // latter.
+        console.warn(`[e2e] humanScroll: scrollY ${before} → ${after}`);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/__tests__/binary.test.ts ADDED Viewed

@@ -0,0 +1,89 @@
+/**
+ * Unit tests for binary resolution. Pure (no Chromium / no spawn).
+ */
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ChromiumNotFoundError, resolveBinary } from "../binary";
+let tmp: string;
+let stubBinary: string;
+const ORIGINAL_ENV = process.env.MOCHI_CHROMIUM_PATH;
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), "mochi-binary-test-"));
+  stubBinary = join(tmp, "chrome-stub");
+  await writeFile(stubBinary, "#!/usr/bin/env false\n", { mode: 0o755 });
+  delete process.env.MOCHI_CHROMIUM_PATH;
+});
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true });
+  if (ORIGINAL_ENV === undefined) {
+    delete process.env.MOCHI_CHROMIUM_PATH;
+  } else {
+    process.env.MOCHI_CHROMIUM_PATH = ORIGINAL_ENV;
+  }
+});
+describe("resolveBinary", () => {
+  it("prefers the explicit `binary` option when valid", async () => {
+    process.env.MOCHI_CHROMIUM_PATH = "/nonsense";
+    const out = await resolveBinary(stubBinary);
+    expect(out).toBe(stubBinary);
+  });
+  it("rejects an explicit binary that does not exist", async () => {
+    let caught: unknown;
+    try {
+      await resolveBinary("/does/not/exist/chromium");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect(String(caught)).toContain("non-existent");
+  });
+  it("falls back to MOCHI_CHROMIUM_PATH when no explicit binary", async () => {
+    process.env.MOCHI_CHROMIUM_PATH = stubBinary;
+    const out = await resolveBinary();
+    expect(out).toBe(stubBinary);
+  });
+  it("rejects MOCHI_CHROMIUM_PATH that does not exist", async () => {
+    process.env.MOCHI_CHROMIUM_PATH = "/missing/chrome";
+    let caught: unknown;
+    try {
+      await resolveBinary();
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect(String(caught)).toContain("non-existent");
+  });
+  it("throws ChromiumNotFoundError when no source resolves", async () => {
+    let caught: unknown;
+    try {
+      await resolveBinary();
+    } catch (err) {
+      caught = err;
+    }
+    // Either ChromiumNotFoundError, or — if the cli happens to export a working
+    // resolveChromiumBinary in this environment — a working path. In CI/local
+    // dev we expect the no-cli path.
+    if (caught instanceof ChromiumNotFoundError) {
+      expect(caught.message).toContain("MOCHI_CHROMIUM_PATH");
+      expect(caught.message).toContain("mochi browsers install");
+    } else if (caught instanceof Error) {
+      // If something else fired (e.g. a future cli implementation returns a
+      // non-existent path), the assertion still verifies we surface a clear
+      // message. The brief allows "error friendly" — we satisfy it either way.
+      expect(String(caught)).toContain("[mochi]");
+    } else {
+      throw new Error(`expected an Error, got ${typeof caught}`);
+    }
+  });
+});

package/src/__tests__/forbidden.test.ts ADDED Viewed

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for the §8.2 forbidden-method runtime assertions.
+ *
+ * Each forbidden constraint gets its own test. These assertions are
+ * non-negotiable mochi stealth invariants — if any of these tests starts
+ * failing, the offending PR violates PLAN.md §8.2.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  assertNotForbidden,
+  FORBIDDEN_METHOD_NAMES,
+  ForbiddenCdpMethodError,
+} from "../cdp/forbidden";
+describe("ForbiddenCdpMethodError + assertNotForbidden (PLAN.md §8.2)", () => {
+  it("rejects Runtime.enable on any target", () => {
+    let thrown: unknown;
+    try {
+      assertNotForbidden("Runtime.enable", {});
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(ForbiddenCdpMethodError);
+    const e = thrown as ForbiddenCdpMethodError;
+    expect(e.method).toBe("Runtime.enable");
+    expect(e.reason).toContain("PLAN.md §8.2");
+  });
+  it("rejects Page.createIsolatedWorld", () => {
+    let thrown: unknown;
+    try {
+      assertNotForbidden("Page.createIsolatedWorld", { frameId: "foo" });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(ForbiddenCdpMethodError);
+    const e = thrown as ForbiddenCdpMethodError;
+    expect(e.method).toBe("Page.createIsolatedWorld");
+    expect(e.reason).toContain("PLAN.md §8.2");
+    expect(e.reason).toContain("Page.createIsolatedWorld");
+  });
+  it("rejects Runtime.evaluate when includeCommandLineAPI === true", () => {
+    let thrown: unknown;
+    try {
+      assertNotForbidden("Runtime.evaluate", {
+        expression: "1+1",
+        includeCommandLineAPI: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(ForbiddenCdpMethodError);
+    const e = thrown as ForbiddenCdpMethodError;
+    expect(e.method).toBe("Runtime.evaluate");
+    expect(e.reason).toContain("includeCommandLineAPI");
+  });
+  it("permits Runtime.evaluate when includeCommandLineAPI is omitted or false", () => {
+    expect(() => assertNotForbidden("Runtime.evaluate", { expression: "1+1" })).not.toThrow();
+    expect(() =>
+      assertNotForbidden("Runtime.evaluate", {
+        expression: "1+1",
+        includeCommandLineAPI: false,
+      }),
+    ).not.toThrow();
+  });
+  it("permits unrelated CDP methods", () => {
+    expect(() => assertNotForbidden("Page.navigate", { url: "about:blank" })).not.toThrow();
+    expect(() => assertNotForbidden("DOM.getDocument")).not.toThrow();
+    expect(() => assertNotForbidden("Target.setAutoAttach", { autoAttach: true })).not.toThrow();
+  });
+  it("FORBIDDEN_METHOD_NAMES includes both unconditional rejects", () => {
+    expect(FORBIDDEN_METHOD_NAMES).toContain("Runtime.enable");
+    expect(FORBIDDEN_METHOD_NAMES).toContain("Page.createIsolatedWorld");
+  });
+});

package/src/__tests__/framer.test.ts ADDED Viewed

@@ -0,0 +1,92 @@
+/**
+ * Unit tests for the NUL-delimited CDP framer.
+ *
+ * Coverage targets:
+ *   - single complete frame in one chunk
+ *   - multiple frames in one chunk
+ *   - one frame split across multiple chunks
+ *   - mid-frame chunk boundary that lands exactly on a NUL
+ *   - empty / NUL-only chunks
+ *   - UTF-8 multi-byte characters spanning chunk boundaries
+ */
+import { describe, expect, it } from "bun:test";
+import { CdpFramer, encodeFrame } from "../cdp/framer";
+const ENC = new TextEncoder();
+function bytes(str: string): Uint8Array {
+  return ENC.encode(str);
+}
+function withNul(str: string): Uint8Array {
+  const inner = bytes(str);
+  const out = new Uint8Array(inner.length + 1);
+  out.set(inner, 0);
+  out[inner.length] = 0;
+  return out;
+}
+describe("CdpFramer", () => {
+  it("yields one frame from one complete chunk", () => {
+    const f = new CdpFramer();
+    const out = f.push(withNul('{"id":1}'));
+    expect(out).toEqual(['{"id":1}']);
+    expect(f.isEmpty).toBe(true);
+  });
+  it("yields multiple frames from a single chunk", () => {
+    const f = new CdpFramer();
+    const a = withNul('{"id":1}');
+    const b = withNul('{"id":2}');
+    const merged = new Uint8Array(a.length + b.length);
+    merged.set(a, 0);
+    merged.set(b, a.length);
+    const out = f.push(merged);
+    expect(out).toEqual(['{"id":1}', '{"id":2}']);
+    expect(f.isEmpty).toBe(true);
+  });
+  it("buffers a partial frame and emits on the chunk that completes it", () => {
+    const f = new CdpFramer();
+    expect(f.push(bytes('{"id":'))).toEqual([]);
+    expect(f.push(bytes('1,"method":"X"'))).toEqual([]);
+    expect(f.isEmpty).toBe(false);
+    expect(f.push(new Uint8Array([0x7d, 0x00]))).toEqual(['{"id":1,"method":"X"}']);
+    expect(f.isEmpty).toBe(true);
+  });
+  it("handles a chunk that ends exactly on a NUL boundary", () => {
+    const f = new CdpFramer();
+    expect(f.push(withNul('{"a":1}'))).toEqual(['{"a":1}']);
+    expect(f.push(withNul('{"b":2}'))).toEqual(['{"b":2}']);
+    expect(f.isEmpty).toBe(true);
+  });
+  it("ignores empty input", () => {
+    const f = new CdpFramer();
+    expect(f.push(new Uint8Array(0))).toEqual([]);
+  });
+  it("drops empty frames between consecutive NULs", () => {
+    const f = new CdpFramer();
+    // <NUL><NUL>{"x":1}<NUL>
+    const buf = new Uint8Array([0, 0, ...bytes('{"x":1}'), 0]);
+    expect(f.push(buf)).toEqual(['{"x":1}']);
+  });
+  it("handles UTF-8 multi-byte chars split across chunks", () => {
+    const f = new CdpFramer();
+    // emoji U+1F600 = 4 bytes F0 9F 98 80
+    const full = withNul('{"emoji":"😀"}');
+    // Split mid-emoji.
+    const splitAt = full.length - 5;
+    expect(f.push(full.subarray(0, splitAt))).toEqual([]);
+    const out = f.push(full.subarray(splitAt));
+    expect(out).toEqual(['{"emoji":"😀"}']);
+  });
+  it("encodeFrame appends exactly one NUL byte", () => {
+    const out = encodeFrame('{"a":1}');
+    expect(out[out.length - 1]).toBe(0);
+    expect(new TextDecoder().decode(out.subarray(0, out.length - 1))).toBe('{"a":1}');
+  });
+});