@lardexx/arenacode 2.8.0 → 2.10.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,17 +149,36 @@ 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` + the .NET UI Automation assemblies. The desktop client
-ships a `windows-use.dll` (exports `wu_call_json`, `wu_free`, `wu_version`) for the same job; the terminal client
-reproduces its behaviour instead of depending on it — the same JSON keys (`bounding_box`, `center`, `control_type`,
-`interactive_elements_text`, `scrollable_elements`, `screenshot_png_base64`), the same ideas: the UI Automation tree of
-the focused window for `ui state`, **unicode typing through `SendInput`** so the clipboard is untouched, extended-key
-flags for arrows/navigation, fuzzy window matching (`ui app --name chrome` finds *"Google Chrome — New Tab"*), and
-numbered labels drawn on the elements for `ui shot --annotated`.
-
-**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. On macOS/Linux the accessibility tree is not read: `ui state` returns windows and geometry as elements.
+**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** is native too, again with no helper binaries: mouse with `CGEventCreateMouseEvent` + `CGEventPost`
+(left/right/middle, double and triple click through the click-state field, drag interpolated), keyboard with
+`CGEventCreateKeyboardEvent` plus modifier *flags* (`cmd`, `ctrl`, `alt`, `shift`) and Apple's fixed `kVK_*`
+keycodes, typing through `CGEventKeyboardSetUnicodeString` so any character or emoji goes in without a layout,
+windows from `CGWindowListCopyWindowInfo` (number, bounds, owner pid), screenshots from `CGDisplayCreateImage`
+converted from BGRA to PNG by the client. `brew install cliclick` is gone. Only what CoreGraphics cannot do —
+launch an app, bring a window to the front, resize it — still uses `osascript`, which ships with macOS. Grant the
+terminal **Accessibility** (input) and **Screen Recording** (pixels) in System Settings → Privacy & Security.
+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,
@@ -241,7 +261,7 @@ The agent never touches your PC directly: it asks, and this client shows a card.
 
 | Card | Source | Executed here |
 |---|---|---|
-| **terminal** | `POST /task/<id>/local-exec` | PowerShell / `cmd` / WSL on Windows, `/bin/sh` elsewhere — asked before running unless `--yes` |
+| **terminal** | `POST /task/<id>/local-exec` | your shell — zsh/bash/sh/fish on macOS and Linux, PowerShell/pwsh/cmd/WSL/Git Bash on Windows (see [Shells](#shells)) — asked before running unless `--yes` |
 | **files** | `local-fs` | `ls`, `stat`, `read`, `write`, `replace`, `find`, `mkdir`, `mv`, `rm`, `pull`, `git_status`, `git_log`, `git_diff`, `git_commit`, `git_revert`, `git_publish` |
 | **plan** | `local-ui` `plan` | approve / reject / ask for a revision, right in the terminal |
 | **file from the agent** | `local_file` | downloaded from `GET /file?raw=1` into the open folder |
@@ -251,17 +271,30 @@ Every file path is resolved **inside the open folder**; paths that escape it are
 the folder itself. Local operations run with your user's permissions — `--confirm-writes` adds a confirmation for
 mutating file operations, `--yes` skips confirmations for terminal commands.
 
-### Not available in a terminal
+### Shells
 
-The desktop client can drive the whole PC (mouse, keyboard, screenshots, app launching — `local-ui`
-`control` / `type` / `keystroke` / `screenshot` / `app` / `state` / `apps` / `multi_*`). A terminal cannot, so
-those cards are answered with an explicit error instead of silently doing nothing:
+Terminal cards run in a real shell, and which one is not fixed:
 
-```json
-{ "ok": false, "error": "operation \"screenshot\" is not available in the terminal client: the ArenaCode desktop client is required" }
+| Platform | Shells |
+|---|---|
+| **Windows** | `powershell` (default), `pwsh`, `cmd`, `wsl`, `bash` (Git Bash when installed, otherwise the WSL bash) |
+| **macOS / Linux** | `zsh`, `bash`, `sh`, `fish`, `dash`, `ksh` — or any absolute path |
+
+The order is: the shell the **bridge** names in the `local-exec` request → the shell **you pinned** →
+your **login shell** (`$SHELL`, e.g. `zsh` on macOS, `bash` on most Linux boxes; PowerShell on Windows).
+Pin it with any of:
+
+```
+arenacode --shell zsh
+arenacode config set shell zsh
+/shell              # in the TUI: pick from the shells installed on this machine
 ```
 
-Everything else in the protocol is implemented.
+`sysinfo` reports `shell` and the full `shells` list, and the `!command` prompt line in the TUI runs in the
+same shell as the agent's cards. Commands are passed as a single argv entry (`zsh -lc '<command>'`,
+`cmd.exe /d /s /c '<command>'`, `powershell.exe -NoProfile -NonInteractive -Command '<command>'`), so quotes,
+`$variables` and pipes are never re-quoted on the way through. `test/shell.js` checks every mapping and runs
+real commands through `sh`/`bash`.
 
 ## How it talks to the bridge
 
@@ -306,7 +339,8 @@ release it on the bridge with `keys unbind <ID>`).
   "pc_access": true,
   "device": "",
   "vision": false,
-  "idle_timeout": 180
+  "idle_timeout": 180,
+  "shell": ""
 }
 ```
 
@@ -315,7 +349,7 @@ Node client cannot, so the key sits in that file — keep it readable only by yo
 (`arenacode keys` on the bridge side: `python3 bridge_server.py keys create "laptop CLI"`).
 
 Environment variables override the file: `ARENACODE_URL`, `ARENACODE_KEY`, `ARENACODE_FOLDER`,
-`ARENACODE_CONFIG`.
+`ARENACODE_SHELL`, `ARENACODE_CONFIG`.
 
 ## Troubleshooting
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.8.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.10.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/shell.js && 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 };