automify 0.1.7 → 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";
@@ -203,15 +203,16 @@ Local desktop computer use controls the native desktop on the machine running yo
 Before running `npx automify-install-desktop`, install the native build tools for your OS:
 
 ```sh
-# Windows: Visual Studio C++ Build Tools plus CMake on PATH.
-winget install Kitware.CMake
+# Windows: Visual Studio 2022 C++ Build Tools plus CMake on PATH.
+winget install --id Microsoft.VisualStudio.2022.BuildTools --exact --override "--passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+winget install --id Kitware.CMake --exact --source winget
 
 # macOS: Xcode Command Line Tools plus CMake on PATH.
 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
@@ -220,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.
+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";
@@ -245,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.7",
+  "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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -23,12 +23,7 @@ const platformPackageName = `@nut-tree/libnut-${process.platform}`;
 const platformPackageDir = join(nutScope, `libnut-${process.platform}`);
 const macPermissionsPackageDir = join(nutScope, "node-mac-permissions");
 
-const runtimeDependencies = [
-  "jimp@1.6.1",
-  "node-abort-controller@3.1.1",
-  "clipboardy@2.3.0",
-  "bindings@1.5.0"
-];
+const runtimeDependencies = ["jimp@1.6.1", "node-abort-controller@3.1.1", "clipboardy@2.3.0", "bindings@1.5.0"];
 
 console.log("Building official nut.js from source.");
 console.log(`Build directory: ${buildRoot}`);
@@ -86,7 +81,9 @@ if (process.platform === "darwin") {
   installWorkspacePackage(macPermissionsSource, macPermissionsPackageDir);
 }
 
-run("node", ["-e", "import('@nut-tree/nut-js').then(() => console.log('nut.js source build import ok'))"], { cwd: root });
+run("node", ["-e", "import('@nut-tree/nut-js').then(() => console.log('nut.js source build import ok'))"], {
+  cwd: root
+});
 
 function cloneOrPull(repo, target, ref) {
   if (existsSync(join(target, ".git"))) {
@@ -123,6 +120,9 @@ function checkBuildPrerequisites() {
   for (const command of ["git", "npm", "cmake"]) {
     if (!commandExists(command)) missing.push(command);
   }
+  if (process.platform === "win32" && !windowsBuildToolsExist()) {
+    missing.push("Visual Studio 2022 C++ Build Tools");
+  }
 
   if (missing.length === 0) return;
 
@@ -132,20 +132,90 @@ 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 C++ Build Tools.");
+    console.error("Windows: install CMake and Visual Studio 2022 C++ Build Tools.");
+    console.error("Make sure the `Desktop development with C++` workload is installed.");
   }
 
   process.exit(1);
 }
 
 function commandExists(command) {
-  const result = spawnSync(resolveCommand(command), ["--version"], {
+  return resolveCommand(command) !== null;
+}
+
+function resolveCommand(command) {
+  for (const candidate of commandCandidates(command)) {
+    const result = spawnSync(candidate.command, [...candidate.args, "--version"], {
+      cwd: root,
+      stdio: "ignore"
+    });
+    if ((result.status ?? 1) === 0) return candidate;
+  }
+  return null;
+}
+
+function commandCandidates(command) {
+  const candidates = [];
+
+  if (process.platform === "win32" && ["npm", "npx"].includes(command)) {
+    candidates.push({ command: `${command}.cmd`, args: [] });
+  }
+
+  const npmCli = npmCliCandidate(command);
+  if (npmCli) candidates.push(npmCli);
+
+  candidates.push({ command, args: [] });
+  return candidates;
+}
+
+function npmCliCandidate(command) {
+  if (!["npm", "npx"].includes(command) || !process.env.npm_execpath) return null;
+  if (command === "npm") return { command: process.execPath, args: [process.env.npm_execpath] };
+
+  const npxExecPath = join(dirname(process.env.npm_execpath), "npx-cli.js");
+  if (!existsSync(npxExecPath)) return null;
+  return { command: process.execPath, args: [npxExecPath] };
+}
+
+function runResolvedCommand(command, args, options = {}) {
+  const candidate = resolveCommand(command) ?? { command, args: [] };
+  return spawnSync(candidate.command, [...candidate.args, ...args], {
     cwd: root,
-    stdio: "ignore"
+    ...options
   });
-  return (result.status ?? 1) === 0;
+}
+
+function windowsBuildToolsExist() {
+  const vswhere = join(
+    process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)",
+    "Microsoft Visual Studio",
+    "Installer",
+    "vswhere.exe"
+  );
+  if (!existsSync(vswhere)) return false;
+
+  const result = spawnSync(
+    vswhere,
+    [
+      "-products",
+      "*",
+      "-version",
+      "[17.0,18.0)",
+      "-requires",
+      "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
+      "-property",
+      "installationPath"
+    ],
+    {
+      cwd: root,
+      encoding: "utf8",
+      stdio: "pipe"
+    }
+  );
+  return (result.status ?? 1) === 0 && result.stdout.trim().length > 0;
 }
 
 function patchPlatformLibnutDependency() {
@@ -326,15 +396,16 @@ exports.default = default_1;
 function installWorkspacePackage(source, target) {
   rmSync(target, { recursive: true, force: true });
   mkdirSync(dirname(target), { recursive: true });
+  const excludedDirs = [join(source, "node_modules"), join(source, "coverage")];
   cpSync(source, target, {
     recursive: true,
-    filter: (file) => !file.includes(`${source}/node_modules`) && !file.includes(`${source}/coverage`)
+    filter: (file) =>
+      !excludedDirs.some((excludedDir) => file === excludedDir || file.startsWith(`${excludedDir}${sep}`))
   });
 }
 
 function run(command, args, options = {}) {
-  const executable = resolveCommand(command);
-  const result = spawnSync(executable, args, {
+  const result = runResolvedCommand(command, args, {
     cwd: options.cwd ?? root,
     env: options.env ?? process.env,
     shell: false,
@@ -367,10 +438,6 @@ function run(command, args, options = {}) {
   return commandResult;
 }
 
-function resolveCommand(command) {
-  return process.platform === "win32" && ["npm", "npx"].includes(command) ? `${command}.cmd` : command;
-}
-
 function runPnpm(args, options = {}) {
   run("npx", ["--yes", "pnpm@8.15.2", ...args], options);
 }

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;