@lardexx/arenacode 2.7.0 → 2.9.0

package/README.md

@@ -30,7 +30,8 @@ Published as [`@lardexx/arenacode`](https://www.npmjs.com/package/@lardexx/arena
 is blocked by npm's similarity check against the existing `arena-code` package, so the scope is required. The
 command is plain `arenacode` in every case.
 
-Requires Node.js 18 or newer. No runtime dependencies.
+Requires Node.js 18 or newer. One runtime dependency, `koffi` (prebuilt FFI bindings for Windows, macOS and Linux,
+no compiler needed): it is how the client reaches `windows-use.dll` on Windows and `libX11`/`libXtst` on Linux.
 
 ## Terminal UI
 
@@ -148,11 +149,29 @@ from the same bridge request the desktop app answers:
 | `ui apps` | the Start menu (Windows), `/Applications` (macOS), `.desktop` entries (Linux) |
 | `ui multi-select`, `ui multi-edit` | built from the primitives above |
 
-No extra install on **Windows** (PowerShell + `user32.dll`). **macOS**: grant Accessibility to your terminal, and
-`brew install cliclick` for the mouse. **Linux** (X11): `sudo apt install xdotool wmctrl imagemagick`; on Wayland
-`xdotool` cannot inject input, so Computer Agent needs XWayland. What this client does *not* have is the desktop's UI
-Automation tree: `ui state` returns windows and pixels, with `interactive_elements` empty, and `--annotated`
-screenshots are plain screenshots.
+**Windows** runs the *same* DLL the desktop client runs. `windows-use.dll` ships inside this package
+(`vendor/windows-use/windows-use.dll`, extracted from `ArenaCode-x64.exe`'s resources) and is called over FFI with
+[koffi](https://koffi.dev) — `wu_call_json` / `wu_free` / `wu_version` — so nothing has to be installed and nothing is
+reimplemented: the UI Automation tree, `SendInput` unicode typing, extended keys for arrows/navigation, Start-menu apps,
+annotated screenshots and fuzzy window matching are all the desktop's own code. The tools and argument names the client
+sends are the ones in the DLL's symbol table (`click_tool`, `move_tool`, `mouse_button_tool`, `scroll_tool`, `type_tool`,
+`shortcut_tool`, `wait_tool`, `app_tool`, `apps_list_tool`, `desktop_state`), and the answers are the same JSON the
+desktop returns (`{"ok":true,"result":…}`, `bounding_box`, `center`, `control_type`, `interactive_elements_text`,
+`screenshot_png_base64` …). `ARENACODE_WINDOWS_USE_DLL` points the client at another copy; if the file is missing it is
+carved out of an installed `ArenaCode-x64.exe` (`ARENACODE_EXE`) by the client's own PE resource reader.
+
+**Linux** talks to the X server directly: `libX11` + `libXtst` through the same FFI layer, **no external tools** — no
+`xdotool`, no `wmctrl`, no `scrot`, no ImageMagick. The pointer is moved with `XTestFakeMotionEvent`, clicks and the wheel
+are `XTestFakeButtonEvent` with buttons 1–5, keys are keysyms mapped to keycodes with `XGetKeyboardMapping`, characters
+outside the keymap borrow an unused keycode with `XChangeKeyboardMapping` and give it back a moment later, windows come
+from `XQueryTree` + `XGetGeometry` + `XTranslateCoordinates` + `_NET_WM_NAME`, focus from `XSetInputFocus`, and
+screenshots are `XGetImage` + `XGetPixel` encoded to PNG by the client itself (zlib). This is what makes it testable:
+`node test/native.js` runs it against a real X server (Xvfb is enough) — a window is created, the client types into it
+and the X events the server delivered are compared with the requested keycodes, chords, buttons and pixels. On Wayland
+the XWayland display is used. `ui app launch` still starts the program's own `.desktop` command; nothing else is spawned.
+
+**macOS**: grant Accessibility to your terminal, and `brew install cliclick` for the mouse. On macOS/Linux the
+accessibility tree is not read: `ui state` returns windows and geometry as elements.
 
 **Ask and Proceed / Proceed.** The desktop's Settings switch, `ctrl+x a` here (also `/ask`, `/proceed`,
 `--proceed`, and `arenacode config set approval proceed`). The default, **Ask and Proceed**, asks before commands,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.7.0",
-  "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands and file operations on your PC. Node port of the ArenaCode desktop client.",
+  "version": "2.9.0",
+  "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands, file operations and computer automation on your PC (windows-use.dll on Windows, Xlib/XTest on Linux, osascript on macOS). Node port of the ArenaCode desktop client.",
   "license": "MIT",
   "type": "commonjs",
   "bin": {
@@ -16,10 +16,11 @@
     "src/",
     "docs/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "vendor/"
   ],
   "scripts": {
-    "test": "node test/integration.js && node test/parity.js && node test/automation.js"
+    "test": "node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js"
   },
   "keywords": [
     "arenacode",
@@ -30,5 +31,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "koffi": "^3.3.6"
   }
 }

package/src/automation/ffi.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// koffi is the only native piece: it ships prebuilt binaries for Windows, macOS and
+// Linux, so the client needs no compiler and no helper executables (xdotool, cliclick,
+// scrot …). Everything below talks to the OS libraries directly.
+
+let koffi = null;
+let loadError = null;
+try {
+  // eslint-disable-next-line global-require
+  koffi = require('koffi');
+} catch (err) {
+  loadError = err;
+}
+
+function available() {
+  return Boolean(koffi);
+}
+
+function requireFfi() {
+  if (!koffi) {
+    throw new Error(
+      `native bindings unavailable (koffi): ${loadError ? loadError.message : 'not installed'}`
+    );
+  }
+  return koffi;
+}
+
+const cache = new Map();
+
+/** lua: loads (and caches) a shared library by name. */
+function lib(name) {
+  if (cache.has(name)) return cache.get(name);
+  const k = requireFfi();
+  let handle = null;
+  try {
+    handle = k.load(name);
+  } catch (err) {
+    cache.set(name, null);
+    return null;
+  }
+  cache.set(name, handle);
+  return handle;
+}
+
+/** Defines a function once per library: fn(lib, 'sig', 'name') */
+function fn(library, name, signature) {
+  const holder = lib(library);
+  if (!holder) return null;
+  const key = `${library}#${name}`;
+  if (cache.has(key)) return cache.get(key);
+  let defined = null;
+  try {
+    defined = holder.func(signature);
+  } catch {
+    defined = null;
+  }
+  cache.set(key, defined);
+  return defined;
+}
+
+module.exports = { available, lib, fn, requireFfi, loadError };