automify 0.1.8 → 0.1.9

package/README.md

@@ -14,14 +14,14 @@ Computer use surfaces:
 | -------------- | --------------------------- | ----------------------------------------------------------- |
 | Browser        | `automify.browser()`        | Playwright browser with screenshots and actions             |
 | Desktop        | `automify.localComputer()`  | Native desktop on the current macOS, Windows, or Linux host |
-| Docker desktop | `automify.dockerComputer()` | Linux desktop inside a Docker container                     |
+| Docker desktop | `automify.dockerComputer()` | Linux desktop inside a running Docker container             |
 
 Command use surfaces:
 
-| Surface    | Factory                | What it does                                         |
-| ---------- | ---------------------- | ---------------------------------------------------- |
-| CLI        | `automify.cli()`       | Terminal automation through model-requested commands |
-| Docker CLI | `automify.dockerCli()` | Containerized terminal automation with shared files  |
+| Surface    | Factory                | What it does                                          |
+| ---------- | ---------------------- | ----------------------------------------------------- |
+| CLI        | `automify.cli()`       | Terminal automation through model-requested commands  |
+| Docker CLI | `automify.dockerCli()` | Containerized terminal automation with running Docker |
 
 OpenAI and Anthropic models are supported, and any other model can be plugged in with a custom provider adapter.
 
@@ -147,7 +147,7 @@ const cli = automify.cli({
 await cli.do("Run the tests and summarize failures");
 ```
 
-Use Docker CLI when command execution should happen inside an isolated container:
+Use Docker CLI when command execution should happen inside an isolated container. Docker must be installed and running before you create the adapter:
 
 ```js
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
@@ -212,7 +212,7 @@ xcode-select --install
 brew install cmake
 
 # Debian/Ubuntu Linux.
-sudo apt-get install -y build-essential cmake libxtst-dev libpng++-dev
+sudo apt-get install -y git build-essential cmake pkg-config libx11-dev libxtst-dev libpng++-dev
 
 # Fedora Linux.
 sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
@@ -221,7 +221,7 @@ sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
 sudo pacman -S --needed base-devel cmake libxtst libpng
 ```
 
-On headless Linux hosts, also install `xvfb` unless you manage `DISPLAY` yourself. On macOS and Windows, `cmake --version` must work in the terminal where you run `npx automify-install-desktop`. On Windows, the VS Code CMake Tools extension is not enough by itself, and Visual Studio 2026 is not currently recognized by the native build chain used by nut.js.
+On Linux, install the full package list before running `npx automify-install-desktop`; the installer checks for command-line build tools but does not verify every native library package. On headless Linux hosts, also install `xvfb` unless you manage `DISPLAY` yourself. On macOS and Windows, `cmake --version` must work in the terminal where you run `npx automify-install-desktop`. On Windows, the VS Code CMake Tools extension is not enough by itself, and Visual Studio 2026 is not currently recognized by the native build chain used by nut.js.
 
 ```js
 import { initAutomify } from "automify";
@@ -246,7 +246,7 @@ try {
 }
 ```
 
-For isolated Linux desktop computer use, use Docker. `dockerComputer()` can run from a macOS, Windows, or Linux host with Docker, but the desktop it controls inside the container is Linux. Docker desktop does not use `automify-install-desktop`; it needs Docker and an initial app command:
+For isolated Linux desktop computer use, use Docker. `dockerComputer()` can run from a macOS, Windows, or Linux host with Docker installed and running, but the desktop it controls inside the container is Linux. Docker desktop does not use `automify-install-desktop`; it needs a running Docker daemon and an initial app command:
 
 ```js
 import { initAutomify } from "automify";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automify",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "AI computer use for browser, CLI, and desktop in Node.js.",
   "homepage": "https://aldovincenti.github.io/automify",
   "bugs": {

package/scripts/install-desktop.js

@@ -132,7 +132,8 @@ function checkBuildPrerequisites() {
   if (process.platform === "darwin") {
     console.error("macOS: install Xcode Command Line Tools with `xcode-select --install` and install CMake.");
   } else if (process.platform === "linux") {
-    console.error("Linux: install CMake, a C/C++ compiler, libxtst-dev, and libpng++-dev.");
+    console.error("Linux: install git, build-essential, cmake, pkg-config, libx11-dev, libxtst-dev, and libpng++-dev.");
+    console.error("The Linux installer does not verify every native library package before building.");
   } else if (process.platform === "win32") {
     console.error("Windows: install CMake and Visual Studio 2022 C++ Build Tools.");
     console.error("Make sure the `Desktop development with C++` workload is installed.");

package/src/lib/argument-reference.js

@@ -51,7 +51,7 @@ export const argumentReference = [
       "logFile"
     ],
     notes:
-      'Use additionalAptPackages to apt-install Debian packages before commands run. Use preset: "repo" to mount the current workspace at /workspace and allow common repo commands. Use logFile to capture CLI and Docker container events.'
+      'Requires Docker to be installed and running. Use additionalAptPackages to apt-install Debian packages before commands run. Use preset: "repo" to mount the current workspace at /workspace and allow common repo commands. Use logFile to capture CLI and Docker container events.'
   },
   {
     surface: "automify.dockerComputer()",
@@ -66,7 +66,7 @@ export const argumentReference = [
       "logFile"
     ],
     notes:
-      "Creates a Docker-backed Linux desktop runner. Pass startupCommand or desktop.startupCommand to launch the initial app. Use additionalAptPackages to apt-install extra Debian packages. Use logFile to capture automation and Docker desktop events. Explicit container names are locked per name until close()."
+      "Creates a Docker-backed Linux desktop runner and requires Docker to be installed and running. Pass startupCommand or desktop.startupCommand to launch the initial app. Use additionalAptPackages to apt-install extra Debian packages. Use logFile to capture automation and Docker desktop events. Explicit container names are locked per name until close()."
   },
   {
     surface: "automify.localComputer()",
@@ -93,6 +93,6 @@ export const argumentReference = [
       "logFile"
     ],
     notes:
-      "container controls Docker and resource limits; startupCommand or desktop.startupCommand is required; shared/sharedFiles control host file access. Use additionalAptPackages to apt-install extra Debian packages and logFile to capture Docker desktop events."
+      "Requires Docker to be installed and running. container controls Docker and resource limits; startupCommand or desktop.startupCommand is required; shared/sharedFiles control host file access. Use additionalAptPackages to apt-install extra Debian packages and logFile to capture Docker desktop events."
   }
 ];

package/src/lib/local-desktop-computer.js

@@ -483,7 +483,7 @@ function localDesktopInstallHelp(platform = process.platform) {
     return "On Windows, install Visual Studio C++ Build Tools and make sure `cmake --version` works, for example after `winget install Kitware.CMake`.";
   }
   if (platform === "linux") {
-    return "On Linux, install the native build tools for your distro: Debian/Ubuntu need `build-essential cmake libxtst-dev libpng++-dev`; Fedora needs `gcc-c++ make cmake libXtst-devel libpng-devel`; Arch needs `base-devel cmake libxtst libpng`. Headless hosts also need `xvfb` unless DISPLAY is managed externally.";
+    return "On Linux, install the native build tools for your distro before running the desktop installer; it does not verify every native library package. Debian/Ubuntu need `git build-essential cmake pkg-config libx11-dev libxtst-dev libpng++-dev`; Fedora needs `gcc-c++ make cmake libXtst-devel libpng-devel`; Arch needs `base-devel cmake libxtst libpng`. Headless hosts also need `xvfb` unless DISPLAY is managed externally.";
   }
   return "Install the native build tools and CMake for this OS.";
 }
@@ -833,15 +833,20 @@ function describePointTransform(x, y, coordinateSpace) {
 
 function buildCoordinateSpace(options, screen) {
   const macOSDisplay = screen.macOSDisplay;
+  const environment = screen.environment ?? options.environment ?? defaultDesktopEnvironment();
   const pixelScale =
     positiveNumber(options.pixelScale) ??
     positiveNumber(macOSDisplay?.backingScaleFactor) ??
-    inferPixelScale(screen, options);
+    inferPixelScale({ ...screen, environment }, options);
   const defaultScale = 1 / pixelScale;
-  const mouseScaleX = scaleRatio(macOSDisplay?.width, screen.displayWidth) ?? defaultScale;
-  const mouseScaleY = scaleRatio(macOSDisplay?.height, screen.displayHeight) ?? defaultScale;
-  const mouseWidth = positiveNumber(macOSDisplay?.width) ?? positiveNumber(screen.displayWidth) * mouseScaleX;
-  const mouseHeight = positiveNumber(macOSDisplay?.height) ?? positiveNumber(screen.displayHeight) * mouseScaleY;
+  const mouseWidth =
+    measuredMouseSize("width", { ...screen, environment, macOSDisplay }) ??
+    scaledDisplaySize(screen.displayWidth, defaultScale);
+  const mouseHeight =
+    measuredMouseSize("height", { ...screen, environment, macOSDisplay }) ??
+    scaledDisplaySize(screen.displayHeight, defaultScale);
+  const mouseScaleX = scaleRatio(mouseWidth, screen.displayWidth) ?? defaultScale;
+  const mouseScaleY = scaleRatio(mouseHeight, screen.displayHeight) ?? defaultScale;
 
   return {
     ...screen,
@@ -856,6 +861,20 @@ function buildCoordinateSpace(options, screen) {
   };
 }
 
+function measuredMouseSize(axis, { environment, macOSDisplay, screenWidth, screenHeight }) {
+  const macOSValue = positiveNumber(macOSDisplay?.[axis]);
+  if (macOSValue) return macOSValue;
+  if (environment === "mac") return null;
+  return positiveNumber(axis === "width" ? screenWidth : screenHeight);
+}
+
+function scaledDisplaySize(size, scale) {
+  const numericSize = positiveNumber(size);
+  const numericScale = positiveNumber(scale);
+  if (!numericSize || !numericScale) return undefined;
+  return numericSize * numericScale;
+}
+
 function scaleRatio(target, source) {
   const numericTarget = positiveNumber(target);
   const numericSource = positiveNumber(source);
@@ -865,18 +884,29 @@ function scaleRatio(target, source) {
 
 function inferPixelScale({ displayWidth, displayHeight, screenWidth, screenHeight }, options = {}) {
   const environment = options.environment ?? defaultDesktopEnvironment();
-  if (environment !== "mac") return 1;
-
   const width = positiveNumber(displayWidth) ?? positiveNumber(screenWidth);
   const height = positiveNumber(displayHeight) ?? positiveNumber(screenHeight);
   if (!width || !height) return 1;
 
+  if (environment !== "mac") {
+    const widthScale = scaleRatio(width, screenWidth);
+    const heightScale = scaleRatio(height, screenHeight);
+    if (widthScale && heightScale && nearlyEqual(widthScale, heightScale)) {
+      return widthScale;
+    }
+    return 1;
+  }
+
   // libnut reports macOS screen size in backing pixels, while CGEvent mouse
   // coordinates use logical points. Built-in Retina displays are 2x here.
   if (width >= 2000 || height >= 1400) return 2;
   return 1;
 }
 
+function nearlyEqual(left, right, epsilon = 0.01) {
+  return Math.abs(left - right) <= epsilon;
+}
+
 function positiveNumber(value) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? number : null;