automify 0.1.9 → 0.1.10

package/README.md

@@ -120,12 +120,12 @@ const browser = await automify.browser({
 });
 
 try {
-  const run = await browser.do("Extract the support email.", {
+  const run = await browser.do("Summarize what you see on the page.", {
     // Optional: structured result shape.
-    output: jsonOutput("support_contact", { email: "string" })
+    output: jsonOutput("page_summary", { title: "string", summary: "string" })
   });
 
-  console.log(run.parsed.email);
+  console.log(run.parsed.title, run.parsed.summary);
 } finally {
   await browser.close();
 }
@@ -208,6 +208,9 @@ winget install --id Microsoft.VisualStudio.2022.BuildTools --exact --override "-
 winget install --id Kitware.CMake --exact --source winget
 
 # macOS: Xcode Command Line Tools plus CMake on PATH.
+# If Homebrew is not installed, install it first:
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
 xcode-select --install
 brew install cmake
 
@@ -221,7 +224,9 @@ sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
 sudo pacman -S --needed base-devel cmake libxtst libpng
 ```
 
-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.
+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, install Homebrew first if `brew` is not available, then install CMake with `brew install cmake`. 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.
+
+`npx automify-install-desktop` stores the compiled desktop runtime outside `node_modules` in a long-term cache, so normal `npm update` runs do not remove it. If a later `npm install` or `npm update` detects that a previously installed desktop runtime no longer matches the current platform, CPU architecture, Node ABI, or pinned nut.js/libnut revisions, Automify rebuilds it automatically during `postinstall`. Default cache roots are `%LOCALAPPDATA%\automify\desktop-runtime` on Windows, `~/Library/Caches/automify/desktop-runtime` on macOS, and `${XDG_CACHE_HOME:-~/.cache}/automify/desktop-runtime` on Linux. Override with `AUTOMIFY_DESKTOP_RUNTIME_DIR`; disable auto-rebuild with `AUTOMIFY_SKIP_DESKTOP_AUTO_REBUILD=1`.
 
 ```js
 import { initAutomify } from "automify";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automify",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "AI computer use for browser, CLI, and desktop in Node.js.",
   "homepage": "https://aldovincenti.github.io/automify",
   "bugs": {
@@ -36,7 +36,7 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "postinstall": "node scripts/install-browser.js",
+    "postinstall": "node scripts/install-browser.js && node scripts/install-desktop-if-needed.js",
     "install:desktop": "node scripts/install-desktop.js",
     "docs:arguments": "node scripts/generate-argument-reference.js",
     "test": "node --test test/*.test.js",

package/scripts/install-browser.js

@@ -9,6 +9,7 @@ if (process.env.AUTOMIFY_SKIP_BROWSER_INSTALL === "1" || process.env.PLAYWRIGHT_
 }
 
 const playwrightCli = join(dirname(require.resolve("playwright")), "cli.js");
+console.log("Automify: installing Playwright browser...");
 const result = spawnSync(process.execPath, [playwrightCli, "install", "chromium"], {
   cwd: process.cwd(),
   stdio: "inherit"

package/scripts/install-desktop-if-needed.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  desktopRuntimeDir,
+  desktopRuntimeIsInstalled,
+  desktopRuntimeKey,
+  findDesktopRuntimeManifests
+} from "../src/lib/desktop-runtime.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+if (process.env.AUTOMIFY_SKIP_DESKTOP_INSTALL === "1" || process.env.AUTOMIFY_SKIP_DESKTOP_AUTO_REBUILD === "1") {
+  process.exit(0);
+}
+
+if (desktopRuntimeIsInstalled()) {
+  process.exit(0);
+}
+
+const existingManifests = findDesktopRuntimeManifests();
+const legacyNodeModulesRuntime = existsSync(join(root, "node_modules", "@nut-tree", "nut-js", "package.json"));
+
+if (existingManifests.length === 0 && !legacyNodeModulesRuntime) {
+  process.exit(0);
+}
+
+console.log("Automify desktop runtime was previously installed but is not compatible with this environment.");
+console.log(`Rebuilding desktop runtime cache: ${desktopRuntimeKey()}`);
+console.log(`Runtime directory: ${desktopRuntimeDir()}`);
+
+const result = spawnSync(process.execPath, [join(__dirname, "install-desktop.js")], {
+  cwd: root,
+  env: process.env,
+  stdio: "inherit"
+});
+
+process.exit(result.status ?? 1);

package/scripts/install-desktop.js

@@ -4,6 +4,15 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } fr
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  DESKTOP_RUNTIME_MANIFEST,
+  desktopRuntimeDir,
+  desktopRuntimeKey,
+  desktopRuntimeManifest,
+  desktopRuntimeNodeModules,
+  desktopRuntimeRefs
+} from "../src/lib/desktop-runtime.js";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "..");
 const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
@@ -12,12 +21,10 @@ const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
 const nutSource = join(buildRoot, "nut.js");
 const libnutSource = join(buildRoot, "libnut-core");
 const macPermissionsSource = join(buildRoot, "node-mac-permissions");
-const refs = {
-  nut: process.env.AUTOMIFY_DESKTOP_NUT_REF ?? "e413fa1f19a19c4631812e4e1eaf47aa732b5cbe",
-  libnutCore: process.env.AUTOMIFY_DESKTOP_LIBNUT_CORE_REF ?? "6bbe5825f1123bcd740117ca932c8b1c6cffb48c",
-  macPermissions: process.env.AUTOMIFY_DESKTOP_MAC_PERMISSIONS_REF ?? "6b6ddee993ddce5071b637e42f6ee1434150d0bb"
-};
-const nodeModules = join(root, "node_modules");
+const refs = desktopRuntimeRefs();
+const runtimeDir = desktopRuntimeDir();
+const runtimeNodeModules = desktopRuntimeNodeModules();
+const nodeModules = runtimeNodeModules;
 const nutScope = join(nodeModules, "@nut-tree");
 const platformPackageName = `@nut-tree/libnut-${process.platform}`;
 const platformPackageDir = join(nutScope, `libnut-${process.platform}`);
@@ -27,6 +34,8 @@ const runtimeDependencies = ["jimp@1.6.1", "node-abort-controller@3.1.1", "clipb
 
 console.log("Building official nut.js from source.");
 console.log(`Build directory: ${buildRoot}`);
+console.log(`Runtime directory: ${runtimeDir}`);
+console.log(`Runtime key: ${desktopRuntimeKey()}`);
 console.log(`nut.js ref: ${refs.nut}`);
 console.log(`libnut-core ref: ${refs.libnutCore}`);
 if (process.platform === "darwin") {
@@ -36,6 +45,8 @@ if (process.platform === "darwin") {
 checkBuildPrerequisites();
 
 mkdirSync(buildRoot, { recursive: true });
+mkdirSync(runtimeDir, { recursive: true });
+writeRuntimePackageJson();
 cloneOrPull("https://github.com/nut-tree/libnut-core.git", libnutSource, refs.libnutCore);
 cloneOrPull("https://github.com/nut-tree/nut.js.git", nutSource, refs.nut);
 if (process.platform === "darwin") {
@@ -69,7 +80,7 @@ writeLibnutImportBridge();
 runPnpm(["--filter", "@nut-tree/nut-js", "run", "compile"], { cwd: nutSource });
 patchNutJimpCompatibility();
 
-run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: root });
+run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: runtimeDir });
 
 installWorkspacePackage(join(nutSource, "core", "shared"), join(nutScope, "shared"));
 installWorkspacePackage(join(nutSource, "core", "provider-interfaces"), join(nutScope, "provider-interfaces"));
@@ -81,9 +92,20 @@ 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
-});
+writeRuntimeManifest();
+run(
+  "node",
+  [
+    "-e",
+    `const { createRequire } = require("node:module");
+const { join } = require("node:path");
+const runtimeDir = process.argv[1];
+createRequire(join(runtimeDir, "automify-desktop-runtime.cjs"))("@nut-tree/nut-js");
+console.log("nut.js source build import ok");`,
+    runtimeDir
+  ],
+  { cwd: root }
+);
 
 function cloneOrPull(repo, target, ref) {
   if (existsSync(join(target, ".git"))) {
@@ -160,22 +182,26 @@ function resolveCommand(command) {
 function commandCandidates(command) {
   const candidates = [];
 
+  const npmCli = npmCliCandidate(command);
+  if (npmCli) candidates.push(npmCli);
+
   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] };
+  if (!["npm", "npx"].includes(command)) return null;
+
+  const npmExecPath =
+    process.env.npm_execpath ?? join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!existsSync(npmExecPath)) return null;
+  if (command === "npm") return { command: process.execPath, args: [npmExecPath] };
 
-  const npxExecPath = join(dirname(process.env.npm_execpath), "npx-cli.js");
+  const npxExecPath = join(dirname(npmExecPath), "npx-cli.js");
   if (!existsSync(npxExecPath)) return null;
   return { command: process.execPath, args: [npxExecPath] };
 }
@@ -404,6 +430,35 @@ function installWorkspacePackage(source, target) {
   });
 }
 
+function writeRuntimePackageJson() {
+  writeText(
+    join(runtimeDir, "package.json"),
+    `${JSON.stringify(
+      {
+        private: true,
+        name: "automify-desktop-runtime",
+        description: "Persistent native runtime cache for Automify local desktop support."
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
+function writeRuntimeManifest() {
+  writeText(
+    join(runtimeDir, DESKTOP_RUNTIME_MANIFEST),
+    `${JSON.stringify(
+      {
+        ...desktopRuntimeManifest(),
+        createdAt: new Date().toISOString()
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
 function run(command, args, options = {}) {
   const result = runResolvedCommand(command, args, {
     cwd: options.cwd ?? root,

package/src/lib/desktop-runtime.js

@@ -0,0 +1,135 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DESKTOP_RUNTIME_PACKAGE = "@nut-tree/nut-js";
+export const DESKTOP_RUNTIME_MANIFEST = "automify-desktop-runtime.json";
+
+export function desktopRuntimeRefs(env = process.env) {
+  return {
+    nut: env.AUTOMIFY_DESKTOP_NUT_REF ?? "e413fa1f19a19c4631812e4e1eaf47aa732b5cbe",
+    libnutCore: env.AUTOMIFY_DESKTOP_LIBNUT_CORE_REF ?? "6bbe5825f1123bcd740117ca932c8b1c6cffb48c",
+    macPermissions: env.AUTOMIFY_DESKTOP_MAC_PERMISSIONS_REF ?? "6b6ddee993ddce5071b637e42f6ee1434150d0bb"
+  };
+}
+
+export function desktopRuntimeCompatibility(env = process.env) {
+  const refs = desktopRuntimeRefs(env);
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    nodeAbi: process.versions.modules,
+    nutRef: refs.nut,
+    libnutCoreRef: refs.libnutCore,
+    macPermissionsRef: process.platform === "darwin" ? refs.macPermissions : undefined
+  };
+}
+
+export function desktopRuntimeKey(compatibility = desktopRuntimeCompatibility()) {
+  return [
+    compatibility.platform,
+    compatibility.arch,
+    `node-${compatibility.nodeAbi}`,
+    `nut-${shortRef(compatibility.nutRef)}`,
+    `libnut-${shortRef(compatibility.libnutCoreRef)}`,
+    compatibility.macPermissionsRef ? `macperms-${shortRef(compatibility.macPermissionsRef)}` : null
+  ]
+    .filter(Boolean)
+    .join("-");
+}
+
+export function defaultDesktopRuntimeRoot(env = process.env) {
+  if (env.AUTOMIFY_DESKTOP_RUNTIME_DIR) {
+    return resolve(env.AUTOMIFY_DESKTOP_RUNTIME_DIR);
+  }
+
+  if (process.platform === "win32") {
+    return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "automify", "desktop-runtime");
+  }
+
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Caches", "automify", "desktop-runtime");
+  }
+
+  return join(env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "automify", "desktop-runtime");
+}
+
+export function desktopRuntimeDir(env = process.env) {
+  return join(defaultDesktopRuntimeRoot(env), desktopRuntimeKey(desktopRuntimeCompatibility(env)));
+}
+
+export function desktopRuntimeNodeModules(env = process.env) {
+  return join(desktopRuntimeDir(env), "node_modules");
+}
+
+export function desktopRuntimePackageJsonPath(env = process.env) {
+  return join(desktopRuntimeNodeModules(env), "@nut-tree", "nut-js", "package.json");
+}
+
+export function desktopRuntimeManifestPath(env = process.env) {
+  return join(desktopRuntimeDir(env), DESKTOP_RUNTIME_MANIFEST);
+}
+
+export function desktopRuntimeManifest(env = process.env) {
+  return {
+    version: 1,
+    package: DESKTOP_RUNTIME_PACKAGE,
+    runtimeDir: desktopRuntimeDir(env),
+    compatibility: desktopRuntimeCompatibility(env)
+  };
+}
+
+export function readDesktopRuntimeManifest(env = process.env) {
+  const path = desktopRuntimeManifestPath(env);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function findDesktopRuntimeManifests(env = process.env) {
+  const root = defaultDesktopRuntimeRoot(env);
+  if (!existsSync(root)) return [];
+
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const runtimeDir = join(root, entry.name);
+      const manifestPath = join(runtimeDir, DESKTOP_RUNTIME_MANIFEST);
+      if (!existsSync(manifestPath)) return null;
+      try {
+        return {
+          runtimeDir,
+          manifestPath,
+          manifest: JSON.parse(readFileSync(manifestPath, "utf8"))
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function desktopRuntimeIsInstalled(env = process.env) {
+  const manifest = readDesktopRuntimeManifest(env);
+  return desktopRuntimeManifestMatches(manifest, env) && existsSync(desktopRuntimePackageJsonPath(env));
+}
+
+export function desktopRuntimeManifestMatches(manifest, env = process.env) {
+  if (!manifest || manifest.version !== 1 || manifest.package !== DESKTOP_RUNTIME_PACKAGE) return false;
+
+  const expected = desktopRuntimeCompatibility(env);
+  const actual = manifest.compatibility ?? {};
+  return (
+    actual.platform === expected.platform &&
+    actual.arch === expected.arch &&
+    actual.nodeAbi === expected.nodeAbi &&
+    actual.nutRef === expected.nutRef &&
+    actual.libnutCoreRef === expected.libnutCoreRef &&
+    actual.macPermissionsRef === expected.macPermissionsRef
+  );
+}
+
+function shortRef(ref) {
+  return String(ref ?? "unknown")
+    .replace(/[^a-zA-Z0-9._-]/g, "_")
+    .slice(0, 12);
+}

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

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
 import { readFile, unlink } from "node:fs/promises";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
@@ -8,6 +10,12 @@ import { promisify } from "node:util";
 import { AutomifyError } from "./errors.js";
 import { acquireAdapterLock } from "./adapter-locks.js";
 import { assertKnownOptions, normalizeLogFile, writeDebugLogFile } from "./runtime.js";
+import {
+  DESKTOP_RUNTIME_PACKAGE,
+  desktopRuntimeDir,
+  desktopRuntimeManifestMatches,
+  desktopRuntimeManifestPath
+} from "./desktop-runtime.js";
 
 const execFileAsync = promisify(execFile);
 const LOCAL_DESKTOP_OPTION_KEYS = new Set([
@@ -448,16 +456,39 @@ async function saveNutImageObject(nut, image, options = {}) {
 }
 
 async function importNut() {
+  let runtimeError;
   try {
-    return await import("@nut-tree/nut-js");
+    const runtimeNut = importNutFromDesktopRuntime();
+    if (runtimeNut) return runtimeNut;
   } catch (error) {
+    runtimeError = error;
+  }
+
+  try {
+    return await import(DESKTOP_RUNTIME_PACKAGE);
+  } catch (error) {
+    const runtimeSuffix = runtimeError ? ` Cached desktop runtime import failed: ${runtimeError.message}` : "";
     throw new AutomifyError(
-      `createLocalDesktopComputer requires the local desktop adapter dependency built from source. ${localDesktopInstallHelp()} After the OS prerequisites are available, run: npx automify-install-desktop`,
+      `createLocalDesktopComputer requires the local desktop adapter dependency built from source. ${localDesktopInstallHelp()} After the OS prerequisites are available, run: npx automify-install-desktop.${runtimeSuffix}`,
       { cause: error }
     );
   }
 }
 
+function importNutFromDesktopRuntime() {
+  const manifestPath = desktopRuntimeManifestPath();
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!desktopRuntimeManifestMatches(manifest)) return null;
+
+  const runtimeRequire = createRequire(join(desktopRuntimeDir(), "automify-desktop-runtime.cjs"));
+  return runtimeRequire(DESKTOP_RUNTIME_PACKAGE);
+}
+
 function normalizeLocalDesktopEnvironment(environment) {
   if (environment == null) return undefined;
   if (typeof environment !== "string" || environment.trim() === "") {