automify 0.1.0

package/examples/cli-docker.js

@@ -0,0 +1,42 @@
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { initAutomify } from "../src/index.js";
+
+const sharedDir = await mkdtemp(join(tmpdir(), "automify-docker-cli-"));
+const dataDir = join(sharedDir, "data");
+const reportPath = join(dataDir, "report.csv");
+const summaryPath = join(dataDir, "summary.json");
+
+await mkdir(dataDir, { recursive: true });
+await writeFile(
+  reportPath,
+  "region,customer,revenue\n" + "North,Ada Corp,1250\n" + "South,Byron Ltd,980\n" + "North,Lovelace Labs,2230\n"
+);
+await writeFile(summaryPath, "{}\n");
+
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const cli = automify.dockerCli({
+  additionalAptPackages: ["coreutils", "nodejs"],
+  shared: { hostPath: sharedDir, containerPath: "/workspace" }
+});
+
+try {
+  const result = await cli.do(
+    "Read data/report.csv, use a Node.js script to calculate revenue by region, update data/summary.json with the result, and report the top region"
+  );
+  const summary = JSON.parse(await readFile(summaryPath, "utf8"));
+  console.log(result.text);
+  console.log(summary);
+  console.log("Shared output file:", summaryPath);
+} finally {
+  await cli.close();
+}

package/examples/custom-computer.js

@@ -0,0 +1,18 @@
+import { createLocalDesktopComputer, initAutomify } from "../src/index.js";
+
+// Run `npm run install:desktop` once before using createLocalDesktopComputer().
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: "gpt-5.5"
+  }
+});
+
+const desktop = automify.computer({
+  computer: await createLocalDesktopComputer()
+});
+
+await desktop.do("Open the calendar app and check my next meeting", {
+  limits: { steps: 12 }
+});

package/examples/custom-model-adapter.js

@@ -0,0 +1,48 @@
+import { initAutomify } from "../src/index.js";
+
+const customModelAdapter = {
+  async respond(payload, context) {
+    // Translate automify's Responses-shaped payload to your provider here.
+    // Then translate your provider's response back into this shape.
+    console.log("Model request:", {
+      model: payload.model,
+      tools: payload.tools?.map((tool) => tool.type ?? tool.name),
+      previousResponseId: payload.previous_response_id,
+      context
+    });
+
+    return {
+      id: `custom_${Date.now()}`,
+      output: [
+        {
+          type: "message",
+          content: [
+            {
+              type: "output_text",
+              text: "This response came from a custom model adapter."
+            }
+          ]
+        }
+      ]
+    };
+  }
+};
+
+const automify = initAutomify({
+  provider: {
+    type: "custom",
+    model: "my-computer-use-model",
+    adapter: customModelAdapter
+  },
+  requestOptions: {
+    temperature: 0.2,
+    metadata: { example: "custom-model-adapter" }
+  }
+});
+
+const cli = automify.cli({
+  cwd: process.cwd()
+});
+
+const result = await cli.do("Explain what model adapter is being used");
+console.log(result.response);

package/examples/desktop-docker.js

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createDockerDesktopComputer, initAutomify } from "../src/index.js";
+
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const computer = await createDockerDesktopComputer({
+  desktop: {
+    startupCommand: "xterm"
+  }
+});
+
+try {
+  const desktop = automify.computer({ computer });
+  const result = await desktop.do(
+    "Use the open terminal to run 'uname -a' and summarize the system information shown on screen.",
+    {
+      screenshots: {
+        initial: join(tmpdir(), "automify-docker-desktop-initial.png"),
+        final: join(tmpdir(), "automify-docker-desktop-final.png")
+      },
+      limits: { steps: 12 }
+    }
+  );
+
+  console.log(result.text);
+  console.log(result.finalScreenshot);
+} finally {
+  await computer.close();
+}

package/examples/desktop-local.js

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createLocalDesktopComputer, initAutomify } from "../src/index.js";
+
+// Run `npm run install:desktop` once before using createLocalDesktopComputer().
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const desktop = automify.computer({
+  computer: await createLocalDesktopComputer()
+});
+
+const instruction =
+  "Open the Calendar app installed on this computer, find the next event after today, and summarize it. Do not create or edit events.";
+
+await desktop.do(instruction, {
+  screenshots: {
+    initial: join(tmpdir(), "automify-local-desktop-initial.png"),
+    final: join(tmpdir(), "automify-local-desktop-final.png")
+  },
+  limits: { steps: 12 }
+});

package/examples/evaluate-image.js

@@ -0,0 +1,26 @@
+import { initAutomify, jsonOutput } from "../src/index.js";
+
+const imagePath = process.argv[2];
+
+if (!imagePath) {
+  throw new Error("Usage: node examples/evaluate-image.js /path/to/image.png");
+}
+
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const cli = automify.cli();
+const result = await cli.do("Evaluate the supplied image and return a concise visual QA report.", {
+  evaluate: [{ path: imagePath, detail: "high" }],
+  output: jsonOutput("image_evaluation", {
+    summary: "string",
+    issues: "array"
+  })
+});
+
+console.log(result.parsed ?? result.text);

package/examples/files-and-shared-folder.js

@@ -0,0 +1,42 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createDockerDesktopComputer, filesToData, initAutomify } from "../src/index.js";
+
+const inputPath = join(tmpdir(), "automify-input.txt");
+await writeFile(inputPath, "Customer: Ada Lovelace\nTask: prepare a short follow-up note\n");
+
+const automify = initAutomify({
+  provider: {
+    type: "openai",
+    apiKey: process.env.OPENAI_API_KEY,
+    model: process.env.OPENAI_MODEL ?? "gpt-5.5"
+  }
+});
+
+const fileData = await filesToData(inputPath);
+const computer = await createDockerDesktopComputer({
+  desktop: {
+    startupCommand: "xterm"
+  },
+  sharedFiles: [{ path: inputPath, targetPath: "inputs/customer.txt" }]
+});
+
+try {
+  const desktop = automify.computer({ computer });
+  const result = await desktop.do("Open the shared file from data and summarize it in the terminal.", {
+    data: {
+      files: fileData,
+      shared: computer.sharedFolder
+    },
+    screenshots: {
+      final: join(tmpdir(), "automify-shared-folder-final.png")
+    }
+  });
+
+  console.log(result.text);
+  console.log(computer.sharedFolder);
+} finally {
+  await computer.close();
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "automify",
+  "version": "0.1.0",
+  "description": "AI computer use for browser, CLI, and desktop in Node.js.",
+  "homepage": "https://aldovincenti.github.io/automify",
+  "bugs": {
+    "url": "https://github.com/aldovincenti/automify/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aldovincenti/automify.git"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./zod": {
+      "types": "./src/zod.d.ts",
+      "import": "./src/zod.js"
+    }
+  },
+  "files": [
+    "src",
+    "scripts",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install-browser.js",
+    "install:desktop": "node scripts/install-desktop.js",
+    "docs:arguments": "node scripts/generate-argument-reference.js",
+    "test": "node --test test/*.test.js",
+    "test:e2e": "node --test test/e2e/*.e2e.test.js",
+    "test:live": "RUN_OPENAI_E2E=1 node --test test/e2e/live-openai.e2e.test.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "jimp": "^0.22.10",
+    "playwright": ">=1.40.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "keywords": [
+    "automation",
+    "computer-use",
+    "browser",
+    "cli",
+    "desktop",
+    "playwright",
+    "openai",
+    "responses"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "prettier": "^3.8.3"
+  }
+}

package/scripts/generate-argument-reference.js

@@ -0,0 +1,17 @@
+import { writeFile } from "node:fs/promises";
+import { argumentReference } from "../src/lib/argument-reference.js";
+
+const rows = argumentReference
+  .map((entry) => `| \`${entry.surface}\` | ${entry.preferred.map((name) => `\`${name}\``).join(", ")} | ${entry.notes} |`)
+  .join("\n");
+
+const markdown = `# Automify Argument Reference
+
+This file is generated from \`src/lib/argument-reference.js\`.
+
+| Surface | Preferred arguments | Notes |
+| ------- | ------------------- | ----- |
+${rows}
+`;
+
+await writeFile(new URL("../docs/argument-reference.md", import.meta.url), markdown);

package/scripts/install-browser.js

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+
+if (process.env.AUTOMIFY_SKIP_BROWSER_INSTALL === "1" || process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === "1") {
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, ["node_modules/playwright/cli.js", "install", "chromium"], {
+  cwd: process.cwd(),
+  stdio: "inherit"
+});
+
+process.exit(result.status ?? 1);

package/scripts/install-desktop.js

@@ -0,0 +1,281 @@
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
+  ? resolve(process.env.AUTOMIFY_DESKTOP_BUILD_DIR)
+  : join(root, ".automify-desktop");
+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 nutScope = join(nodeModules, "@nut-tree");
+const platformPackageName = `@nut-tree/libnut-${process.platform}`;
+const platformPackageDir = join(nutScope, `libnut-${process.platform}`);
+const macPermissionsPackageDir = join(nutScope, "node-mac-permissions");
+
+const runtimeDependencies = [
+  "jimp@0.22.10",
+  "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}`);
+console.log(`nut.js ref: ${refs.nut}`);
+console.log(`libnut-core ref: ${refs.libnutCore}`);
+if (process.platform === "darwin") {
+  console.log(`node-mac-permissions ref: ${refs.macPermissions}`);
+}
+
+checkBuildPrerequisites();
+
+mkdirSync(buildRoot, { recursive: true });
+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") {
+cloneOrPull("https://github.com/nut-tree/node-mac-permissions.git", macPermissionsSource, refs.macPermissions);
+}
+
+patchNutWorkspace();
+
+run("npm", ["install"], { cwd: libnutSource });
+buildLibnutCore();
+
+run("node", ["patch-packagename.js"], {
+  cwd: libnutSource,
+  env: { ...process.env, CI: "1" }
+});
+
+if (process.platform === "darwin") {
+  run("npm", ["install"], { cwd: macPermissionsSource });
+  run("npm", ["run", "build:release"], { cwd: macPermissionsSource });
+}
+
+patchPlatformLibnutDependency();
+
+runPnpm(["install"], { cwd: nutSource });
+runPnpm(["--filter", "@nut-tree/shared", "run", "compile"], { cwd: nutSource });
+runPnpm(["--filter", "@nut-tree/provider-interfaces", "run", "compile"], { cwd: nutSource });
+runPnpm(["--filter", "@nut-tree/default-clipboard-provider", "run", "compile"], { cwd: nutSource });
+runPnpm(["--filter", "@nut-tree/libnut", "run", "compile"], { cwd: nutSource });
+runPnpm(["--filter", "@nut-tree/nut-js", "run", "compile"], { cwd: nutSource });
+
+run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: root });
+
+installWorkspacePackage(join(nutSource, "core", "shared"), join(nutScope, "shared"));
+installWorkspacePackage(join(nutSource, "core", "provider-interfaces"), join(nutScope, "provider-interfaces"));
+installWorkspacePackage(join(nutSource, "providers", "clipboardy"), join(nutScope, "default-clipboard-provider"));
+installWorkspacePackage(join(nutSource, "providers", "libnut"), join(nutScope, "libnut"));
+installWorkspacePackage(join(nutSource, "core", "nut.js"), join(nutScope, "nut-js"));
+installWorkspacePackage(libnutSource, platformPackageDir);
+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 });
+
+function cloneOrPull(repo, target, ref) {
+  if (existsSync(join(target, ".git"))) {
+    run("git", ["-C", target, "fetch", "--depth", "1", "origin", ref]);
+    checkoutFetchedRef(target, ref);
+    run("git", ["-C", target, "clean", "-fd"]);
+    return;
+  }
+
+  rmSync(target, { recursive: true, force: true });
+  run("git", ["clone", "--depth", "1", "--branch", ref, repo, target], { exitOnError: false }).ok ||
+    run("git", ["clone", "--depth", "1", repo, target]);
+  if (!currentRefMatches(target, ref)) {
+    run("git", ["-C", target, "fetch", "--depth", "1", "origin", ref]);
+    checkoutFetchedRef(target, ref);
+  }
+}
+
+function checkoutFetchedRef(target, ref) {
+  run("git", ["-C", target, "checkout", "--detach", "FETCH_HEAD"]);
+}
+
+function currentRefMatches(target, ref) {
+  const result = spawnSync("git", ["-C", target, "rev-parse", "--verify", `${ref}^{commit}`], {
+    cwd: root,
+    encoding: "utf8"
+  });
+  return (result.status ?? 1) === 0;
+}
+
+function checkBuildPrerequisites() {
+  const missing = [];
+
+  for (const command of ["git", "npm", "cmake"]) {
+    if (!commandExists(command)) missing.push(command);
+  }
+
+  if (missing.length === 0) return;
+
+  console.error(`Missing required desktop build tool(s): ${missing.join(", ")}`);
+  console.error("Install the native build prerequisites, then rerun: npm run install:desktop");
+
+  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.");
+  } else if (process.platform === "win32") {
+    console.error("Windows: install CMake and Visual Studio C++ Build Tools.");
+  }
+
+  process.exit(1);
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ["--version"], {
+    cwd: root,
+    stdio: "ignore"
+  });
+  return (result.status ?? 1) === 0;
+}
+
+function patchPlatformLibnutDependency() {
+  const packagePath = join(nutSource, "providers", "libnut", "package.json");
+  const packageJson = JSON.parse(readText(packagePath));
+  packageJson.dependencies = {
+    [platformPackageName]: `file:${libnutSource}`
+  };
+  writeText(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+
+function buildLibnutCore() {
+  const build = run("npm", ["run", "build:release"], {
+    cwd: libnutSource,
+    exitOnError: false
+  });
+
+  if (build.ok) return;
+
+  if (!shouldPatchMacosSdk15Build(build)) {
+    process.exit(build.status ?? 1);
+  }
+
+  console.warn("libnut-core failed against the macOS SDK 15 screen-capture availability check.");
+  console.warn("Applying local compatibility patch for CGDisplayCreateImageForRect and retrying.");
+  patchLibnutCoreForMacosSdk15();
+  run("npm", ["run", "build:release"], { cwd: libnutSource });
+}
+
+function shouldPatchMacosSdk15Build(result) {
+  if (process.platform !== "darwin") return false;
+  if (process.env.AUTOMIFY_DESKTOP_DISABLE_MACOS_SDK15_PATCH === "1") return false;
+  return `${result.stdout}\n${result.stderr}`.includes("CGDisplayCreateImageForRect");
+}
+
+function patchLibnutCoreForMacosSdk15() {
+  if (process.platform !== "darwin") return;
+
+  const screenGrabPath = join(libnutSource, "src", "macos", "screengrab.m");
+  let source = readText(screenGrabPath);
+
+  if (source.includes("AutomifyCGDisplayCreateImageForRect")) return;
+
+  source = source.replace(
+    "#import <Cocoa/Cocoa.h>",
+    `#import <Cocoa/Cocoa.h>
+#include <dlfcn.h>
+
+typedef CGImageRef (*AutomifyCGDisplayCreateImageForRectFn)(CGDirectDisplayID, CGRect);
+
+static CGImageRef AutomifyCGDisplayCreateImageForRect(CGDirectDisplayID displayID, CGRect rect) {
+    AutomifyCGDisplayCreateImageForRectFn fn = (AutomifyCGDisplayCreateImageForRectFn)dlsym(RTLD_DEFAULT, "CGDisplayCreateImageForRect");
+    if (!fn) { return NULL; }
+    return fn(displayID, rect);
+}`
+  );
+  source = source.replace("CGDisplayCreateImageForRect(displayID,", "AutomifyCGDisplayCreateImageForRect(displayID,");
+
+  writeText(screenGrabPath, source);
+}
+
+function patchNutWorkspace() {
+  writeText(
+    join(nutSource, "pnpm-workspace.yaml"),
+    `packages:
+  - 'core/*'
+  - 'providers/libnut'
+  - 'providers/clipboardy'
+`
+  );
+
+  for (const relativePath of [
+    ["providers", "clipboardy", "package.json"],
+    ["providers", "libnut", "package.json"]
+  ]) {
+    const packagePath = join(nutSource, ...relativePath);
+    const packageJson = JSON.parse(readText(packagePath));
+    delete packageJson.peerDependencies;
+    writeText(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+  }
+}
+
+function installWorkspacePackage(source, target) {
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(dirname(target), { recursive: true });
+  cpSync(source, target, {
+    recursive: true,
+    filter: (file) => !file.includes(`${source}/node_modules`) && !file.includes(`${source}/coverage`)
+  });
+}
+
+function run(command, args, options = {}) {
+  const executable = process.platform === "win32" && ["npm", "npx"].includes(command) ? `${command}.cmd` : command;
+  const result = spawnSync(executable, args, {
+    cwd: options.cwd ?? root,
+    env: options.env ?? process.env,
+    shell: false,
+    stdio: options.exitOnError === false ? "pipe" : "inherit",
+    encoding: options.exitOnError === false ? "utf8" : undefined
+  });
+  const commandResult = {
+    ok: (result.status ?? 1) === 0,
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error
+  };
+
+  if (!commandResult.ok) {
+    if (options.exitOnError === false) {
+      if (commandResult.stdout) process.stdout.write(commandResult.stdout);
+      if (commandResult.stderr) process.stderr.write(commandResult.stderr);
+      return commandResult;
+    }
+    if (options.allowMissing && result.error?.code === "ENOENT") return;
+    process.exit(commandResult.status);
+  }
+
+  if (options.exitOnError === false) {
+    if (commandResult.stdout) process.stdout.write(commandResult.stdout);
+    if (commandResult.stderr) process.stderr.write(commandResult.stderr);
+  }
+
+  return commandResult;
+}
+
+function runPnpm(args, options = {}) {
+  run("npx", ["--yes", "pnpm@8.15.2", ...args], options);
+}
+
+function readText(path) {
+  return readFileSync(path, "utf8");
+}
+
+function writeText(path, text) {
+  writeFileSync(path, text);
+}