jev-ra 0.0.1 → 0.1.0

package/README.md

@@ -1,5 +1,59 @@
-# jev-ra
+# jev-ra (npm launcher)
 
-Browser use for coding agents (Claude Code, Codex, any MCP client), driven by TypeSafe Jev decisions.
+A fast browser-use layer for CLI coding agents. Claude Code, Codex, or any MCP client hands jev-ra a
+goal; TypeSafe Jev picks the operation and the target element for every step in one round trip, in
+about 300 ms. Measured 3-5x faster than browser-use on the same tasks, same Chrome, same key.
 
-This version only reserves the name. The first working release is in progress at https://github.com/brnyxx/jev-ra.
+**This package contains no jev-ra code.** It is a launcher: it finds [uv](https://docs.astral.sh/uv/),
+offers to install it the first time, and then runs the Python package from PyPI through `uvx`,
+pinned to this package's own version. Use it when you do not want to set Python up yourself.
+
+```sh
+export OPENROUTER_API_KEY=sk-or-...
+npx -y jev-ra install claude     # or: install codex
+npx -y jev-ra doctor
+```
+
+`install` registers `uvx jev-ra mcp` as an MCP server in Claude Code or Codex and forwards the key
+from your environment without printing it. `doctor` ends with one live decision and its latency:
+
+```
+decision: DONE in 314 ms via typesafe/jev-1.13
+```
+
+From the shell, every subcommand of [the CLI](https://github.com/brnyxx/jev-ra/blob/main/docs/USAGE.md)
+works the same way:
+
+```sh
+npx -y jev-ra run https://en.wikipedia.org/wiki/Main_Page "Open the Godel incompleteness article." \
+  --value "search_query=Godel incompleteness theorems"
+npx -y jev-ra search "python 3.12 release date" "the exact release date, with source"
+```
+
+## Any other MCP client
+
+```json
+{ "mcpServers": { "jev-ra": { "command": "npx", "args": ["-y", "jev-ra", "mcp"] } } }
+```
+
+The server inherits the environment it is started in, so the key can come from there. `uvx` in place
+of `npx -y` does the same thing without Node.
+
+## Flags this launcher understands
+
+| flag | effect |
+|---|---|
+| `--yes` | install uv without asking, when it is missing |
+| `--no-install` | never install uv; print how to do it and exit 2 |
+
+Neither reaches the Python side. `JEV_RA_FROM` overrides the pinned package specifier, for a local
+wheel or a fork: `JEV_RA_FROM=./jev_ra-0.1.0-py3-none-any.whl npx jev-ra --version`.
+
+## Requirements
+
+Node 20 or newer, and a Chrome, Chromium or Edge installed. jev-ra launches its own Chrome on a
+dedicated profile, or attaches to `BU_CDP_URL` if you set it; `JEV_RA_CHROME` names a binary it
+would not find on its own. You need an API key in the environment: `OPENROUTER_API_KEY` (no
+TypeSafe account needed) or `TYPESAFE_API_KEY`.
+
+MIT licensed. Source, docs, benchmarks and the real-site corpus: https://github.com/brnyxx/jev-ra

package/bin/jev-ra.js

@@ -1,3 +1,88 @@
 #!/usr/bin/env node
-console.error("jev-ra 0.0.1 only reserves the package name. The first release is in progress: https://github.com/brnyxx/jev-ra");
-process.exit(2);
+// A launcher, not a reimplementation: every argument goes to `uvx jev-ra@<pinned>`.
+// uv builds and caches the Python environment, so there is nothing to install first.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import process from "node:process";
+
+export const PINNED = "0.1.0";
+export const INSTALL_HINT = [
+  "jev-ra runs on uv, which is not on PATH.",
+  "Install it with one of:",
+  "  curl -LsSf https://astral.sh/uv/install.sh | sh     (macOS, Linux)",
+  "  powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"   (Windows)",
+  "  brew install uv",
+  "then run this command again.",
+].join("\n");
+
+export function findUv(which = whichSync) {
+  return which("uv");
+}
+
+export function whichSync(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const found = spawnSync(finder, [command], { encoding: "utf8" });
+  if (found.status !== 0) return null;
+  const first = (found.stdout || "").split(/\r?\n/).find(Boolean);
+  return first ? first.trim() : null;
+}
+
+export function splitArgs(argv) {
+  const passthrough = argv.filter((item) => item !== "--yes" && item !== "--no-install");
+  return {
+    args: passthrough,
+    assumeYes: argv.includes("--yes"),
+    allowInstall: !argv.includes("--no-install"),
+  };
+}
+
+// JEV_RA_FROM lets CI and anyone pinning a fork point uvx at a wheel or a git ref instead.
+export function uvxArgs(args, pinned = PINNED, from = process.env.JEV_RA_FROM) {
+  return ["--from", from || `jev-ra==${pinned}`, "jev-ra", ...args];
+}
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) return false;
+  const reader = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await new Promise((resolve) => reader.question(`${question} [y/N] `, resolve));
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    reader.close();
+  }
+}
+
+function installUv() {
+  const command =
+    process.platform === "win32"
+      ? ["powershell", ["-c", "irm https://astral.sh/uv/install.ps1 | iex"]]
+      : ["sh", ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"]];
+  execFileSync(command[0], command[1], { stdio: "inherit" });
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { args, assumeYes, allowInstall } = splitArgs(argv);
+  let uv = findUv();
+  if (!uv && allowInstall) {
+    const agreed = assumeYes || (await confirm("Install uv now?"));
+    if (agreed) {
+      installUv();
+      uv = findUv();
+    }
+  }
+  if (!uv) {
+    process.stderr.write(`${INSTALL_HINT}\n`);
+    return 2;
+  }
+  try {
+    execFileSync("uvx", uvxArgs(args), { stdio: "inherit" });
+    return 0;
+  } catch (error) {
+    return typeof error.status === "number" ? error.status : 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = await main();
+}

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "jev-ra",
-  "version": "0.0.1",
-  "description": "Browser use for coding agents, driven by TypeSafe Jev decisions. Name reserved; first release coming soon.",
-  "bin": { "jev-ra": "bin/jev-ra.js" },
-  "files": ["bin", "README.md"],
-  "repository": { "type": "git", "url": "https://github.com/brnyxx/jev-ra" },
-  "homepage": "https://github.com/brnyxx/jev-ra",
+  "version": "0.1.0",
+  "description": "A fast browser-use layer for CLI coding agents: MCP server, CLI and Python API. This package is a launcher; it runs the Python tool through uv.",
+  "keywords": ["browser", "browser-automation", "mcp", "mcp-server", "agent", "ai-agent", "cdp",
+    "chrome", "automation", "claude-code", "codex", "cursor", "typesafe", "jev", "web-agent"],
   "license": "MIT",
   "author": "Brian Kim",
-  "engines": { "node": ">=20" }
+  "homepage": "https://github.com/brnyxx/jev-ra",
+  "repository": { "type": "git", "url": "git+https://github.com/brnyxx/jev-ra.git", "directory": "npm" },
+  "bugs": { "url": "https://github.com/brnyxx/jev-ra/issues" },
+  "bin": { "jev-ra": "bin/jev-ra.js" },
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "files": ["bin/", "README.md"],
+  "scripts": { "test": "node --test test/*.test.mjs" }
 }