usecomputer 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+<!-- Purpose: track notable user-facing changes for npm releases. -->
+
+# Changelog
+
+All notable changes to `usecomputer` will be documented in this file.
+
+## 0.0.3
+
+- Implement real screenshot capture + PNG file writing on macOS.
+- Screenshot path handling now uses the requested output path reliably.
+- Unimplemented commands now return explicit `TODO not implemented: ...` errors.
+- Clarify `--display` index behavior as 0-based in help/docs.
+
+## 0.0.2
+
+- Publish macOS native binaries for both `darwin-arm64` and `darwin-x64`.
+- Add package metadata/docs for npm distribution.
+- Improve CLI coordinate input with `-x` / `-y` flags.
+
+## 0.0.1
+
+- Initial npm package release for macOS.
+- Native Zig + Quartz mouse actions:
+  - `click`
+  - `mouse move`
+  - `mouse down`
+  - `mouse up`
+  - `mouse position`
+  - `hover`
+  - `drag`
+- CLI coordinates improved with `-x` and `-y` flags.

package/README.md

@@ -0,0 +1,51 @@
+<!-- Purpose: npm package usage and install guide for usecomputer CLI. -->
+
+# usecomputer
+
+`usecomputer` is a macOS desktop automation CLI for AI agents.
+
+It can move the mouse, click, drag, and query cursor position using native
+Quartz events through a Zig N-API module.
+
+## Install
+
+```bash
+npm install -g usecomputer
+```
+
+## Requirements
+
+- macOS (Darwin)
+- Accessibility permission enabled for your terminal app
+
+## Quick start
+
+```bash
+usecomputer mouse position --json
+usecomputer mouse move -x 500 -y 500
+usecomputer click -x 500 -y 500 --button left --count 1
+```
+
+## Coordinate options
+
+Commands that target coordinates accept `-x` and `-y` flags:
+
+- `usecomputer click -x <n> -y <n>`
+- `usecomputer hover -x <n> -y <n>`
+- `usecomputer mouse move -x <n> -y <n>`
+
+Legacy coordinate forms are also accepted where available.
+
+## Display index options
+
+For commands that accept `--display`, the index is 0-based:
+
+- `0` = first display
+- `1` = second display
+- `2` = third display
+
+Example:
+
+```bash
+usecomputer screenshot ./shot.png --display 0 --json
+```

package/bin.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-import './dist/cli.js'
+import { runCli } from './dist/cli.js'
+
+runCli()

package/build.zig

@@ -0,0 +1,53 @@
+// Build script for usecomputer Zig N-API native module artifacts.
+
+const std = @import("std");
+const napigen = @import("napigen");
+
+const LIB_NAME = "usecomputer";
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const lib_mod = b.createModule(.{
+        .root_source_file = b.path("zig/src/lib.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    lib_mod.addImport("napigen", b.dependency("napigen", .{}).module("napigen"));
+    lib_mod.addImport("objc", b.dependency("zig_objc", .{
+        .target = target,
+        .optimize = optimize,
+    }).module("objc"));
+
+    const lib = b.addLibrary(.{
+        .name = LIB_NAME,
+        .root_module = lib_mod,
+        .linkage = .dynamic,
+    });
+
+    if (target.result.os.tag == .macos) {
+        lib.root_module.linkFramework("CoreGraphics", .{});
+        lib.root_module.linkFramework("CoreFoundation", .{});
+        lib.root_module.linkFramework("ImageIO", .{});
+    }
+
+    napigen.setup(lib);
+    b.installArtifact(lib);
+
+    const copy_node_step = b.addInstallLibFile(lib.getEmittedBin(), LIB_NAME ++ ".node");
+    b.getInstallStep().dependOn(&copy_node_step.step);
+
+    const test_mod = b.createModule(.{
+        .root_source_file = b.path("zig/src/lib.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const test_step = b.step("test", "Run Zig unit tests");
+    const test_exe = b.addTest(.{
+        .root_module = test_mod,
+    });
+    const run_test = b.addRunArtifact(test_exe);
+    test_step.dependOn(&run_test.step);
+}

package/build.zig.zon

@@ -0,0 +1,21 @@
+// Zig package manifest for the usecomputer native addon dependencies.
+.{
+    .name = .usecomputer,
+    .version = "0.1.0",
+    .fingerprint = 0x28c2cde2d2b298eb,
+    .dependencies = .{
+        .napigen = .{
+            .url = "git+https://github.com/cztomsik/napigen?ref=main#bc2c8259d95be774847e60fce9bfc203ab623b30",
+            .hash = "napigen-0.1.0-YpiIumJ9AAA4yVKISHKfN_2H0u7-su18jRHSSq_UUTNN",
+        },
+        .zig_objc = .{
+            .url = "git+https://github.com/mitchellh/zig-objc?ref=main#27d0e03242e7ee6842bf8a86d2e0bb1f586a9847",
+            .hash = "zig_objc-0.0.0-Ir_Sp7oUAQC3JpeR9EGUFGcHRSx_33IehitnjBCy-CwD",
+        },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "zig",
+    },
+}

package/dist/bridge-contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bridge-contract.test.d.ts.map

package/dist/bridge-contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-contract.test.d.ts","sourceRoot":"","sources":["../src/bridge-contract.test.ts"],"names":[],"mappings":""}

package/dist/bridge-contract.test.js

@@ -0,0 +1,74 @@
+// Contract tests for command names and payloads emitted to the native bridge.
+import { describe, expect, test } from 'vitest';
+import { createBridgeFromNative } from './bridge.js';
+function createFakeNative({ calls }) {
+    return {
+        execute(command, payloadJson) {
+            const payload = JSON.parse(payloadJson);
+            calls.push({ command, payload });
+            if (command === 'mouse-position') {
+                return JSON.stringify({ ok: true, data: { x: 10, y: 20 } });
+            }
+            if (command === 'display-list') {
+                return JSON.stringify({
+                    ok: true,
+                    data: [
+                        { id: 1, name: 'Built-in', x: 0, y: 0, width: 1512, height: 982, scale: 2, isPrimary: true },
+                    ],
+                });
+            }
+            if (command === 'clipboard-get') {
+                return JSON.stringify({ ok: true, data: { text: 'hello' } });
+            }
+            if (command === 'screenshot') {
+                return JSON.stringify({ ok: true, data: { path: '/tmp/test.png' } });
+            }
+            return JSON.stringify({ ok: true, data: null });
+        },
+    };
+}
+describe('native bridge contract', () => {
+    test('maps high-level calls to native commands', async () => {
+        const calls = [];
+        const bridge = createBridgeFromNative({ nativeModule: createFakeNative({ calls }) });
+        await bridge.click({
+            point: { x: 100, y: 200 },
+            button: 'left',
+            count: 2,
+            modifiers: ['cmd'],
+        });
+        await bridge.typeText({ text: 'hello', delayMs: 30 });
+        await bridge.press({ key: 'enter', count: 1 });
+        await bridge.scroll({ direction: 'down', amount: 300 });
+        await bridge.drag({ from: { x: 10, y: 10 }, to: { x: 200, y: 120 }, button: 'left' });
+        await bridge.hover({ x: 33, y: 44 });
+        await bridge.mouseMove({ x: 60, y: 70 });
+        await bridge.mouseDown({ button: 'left' });
+        await bridge.mouseUp({ button: 'left' });
+        await bridge.mousePosition();
+        await bridge.displayList();
+        await bridge.clipboardGet();
+        await bridge.clipboardSet({ text: 'copied' });
+        await bridge.screenshot({ path: './out.png' });
+        expect(calls.map((call) => {
+            return call.command;
+        })).toMatchInlineSnapshot(`
+      [
+        "click",
+        "type-text",
+        "press",
+        "scroll",
+        "drag",
+        "hover",
+        "mouse-move",
+        "mouse-down",
+        "mouse-up",
+        "mouse-position",
+        "display-list",
+        "clipboard-get",
+        "clipboard-set",
+        "screenshot",
+      ]
+    `);
+    });
+});

package/dist/bridge.d.ts

@@ -0,0 +1,7 @@
+import { type NativeModule } from './native-lib.js';
+import type { UseComputerBridge } from './types.js';
+export declare function createBridgeFromNative({ nativeModule }: {
+    nativeModule: NativeModule | null;
+}): UseComputerBridge;
+export declare function createBridge(): UseComputerBridge;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAEA,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC3D,OAAO,KAAK,EASV,iBAAiB,EAElB,MAAM,YAAY,CAAA;AA6CnB,wBAAgB,sBAAsB,CAAC,EAAE,YAAY,EAAE,EAAE;IAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,GAAG,iBAAiB,CA+FjH;AAED,wBAAgB,YAAY,IAAI,iBAAiB,CAEhD"}

package/dist/bridge.js

@@ -0,0 +1,130 @@
+// Native bridge that maps typed TS calls to the Zig N-API command dispatcher.
+import { native } from './native-lib.js';
+const unavailableError = 'Native backend is unavailable. Build it with `pnpm build:native` or `zig build` in usecomputer/.';
+function execute({ nativeModule, command, payload, }) {
+    const response = nativeModule.execute(command, JSON.stringify(payload));
+    const parsed = JSON.parse(response);
+    if (!parsed.ok) {
+        return new Error(parsed.error || `Native command failed: ${command}`);
+    }
+    return parsed.data;
+}
+function unavailableBridge() {
+    const fail = async () => {
+        throw new Error(unavailableError);
+    };
+    return {
+        screenshot: fail,
+        click: fail,
+        typeText: fail,
+        press: fail,
+        scroll: fail,
+        drag: fail,
+        hover: fail,
+        mouseMove: fail,
+        mouseDown: fail,
+        mouseUp: fail,
+        mousePosition: fail,
+        displayList: fail,
+        clipboardGet: fail,
+        clipboardSet: fail,
+    };
+}
+export function createBridgeFromNative({ nativeModule }) {
+    if (!nativeModule) {
+        return unavailableBridge();
+    }
+    return {
+        async screenshot(input) {
+            const result = execute({ nativeModule, command: 'screenshot', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+            return result;
+        },
+        async click(input) {
+            const result = execute({ nativeModule, command: 'click', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async typeText(input) {
+            const result = execute({ nativeModule, command: 'type-text', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async press(input) {
+            const result = execute({ nativeModule, command: 'press', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async scroll(input) {
+            const result = execute({ nativeModule, command: 'scroll', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async drag(input) {
+            const result = execute({ nativeModule, command: 'drag', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async hover(input) {
+            const result = execute({ nativeModule, command: 'hover', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async mouseMove(input) {
+            const result = execute({ nativeModule, command: 'mouse-move', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async mouseDown(input) {
+            const result = execute({ nativeModule, command: 'mouse-down', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async mouseUp(input) {
+            const result = execute({ nativeModule, command: 'mouse-up', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+        async mousePosition() {
+            const result = execute({ nativeModule, command: 'mouse-position', payload: {} });
+            if (result instanceof Error) {
+                throw result;
+            }
+            return result;
+        },
+        async displayList() {
+            const result = execute({ nativeModule, command: 'display-list', payload: {} });
+            if (result instanceof Error) {
+                throw result;
+            }
+            return result;
+        },
+        async clipboardGet() {
+            const result = execute({ nativeModule, command: 'clipboard-get', payload: {} });
+            if (result instanceof Error) {
+                throw result;
+            }
+            return result.text;
+        },
+        async clipboardSet(input) {
+            const result = execute({ nativeModule, command: 'clipboard-set', payload: input });
+            if (result instanceof Error) {
+                throw result;
+            }
+        },
+    };
+}
+export function createBridge() {
+    return createBridgeFromNative({ nativeModule: native });
+}

package/dist/cli-parsing.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-parsing.test.d.ts.map

package/dist/cli-parsing.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-parsing.test.d.ts","sourceRoot":"","sources":["../src/cli-parsing.test.ts"],"names":[],"mappings":""}

package/dist/cli-parsing.test.js

@@ -0,0 +1,30 @@
+// Tests for goke CLI parsing on key automation commands.
+import { describe, expect, test } from 'vitest';
+import { createCli } from './cli.js';
+describe('usecomputer cli parsing', () => {
+    test('parses click options with typed defaults', () => {
+        const cli = createCli();
+        const parsed = cli.parse(['node', 'usecomputer', 'click', '100,200', '--count', '2'], { run: false });
+        expect(parsed.args[0]).toBe('100,200');
+        expect(parsed.options.count).toBe(2);
+        expect(parsed.options.button).toBe('left');
+    });
+    test('parses screenshot options', () => {
+        const cli = createCli();
+        const parsed = cli.parse(['node', 'usecomputer', 'screenshot', './shot.png', '--display', '2', '--region', '0,0,120,80'], { run: false });
+        expect(parsed.args[0]).toBe('./shot.png');
+        expect(parsed.options.display).toBe(2);
+        expect(parsed.options.region).toBe('0,0,120,80');
+    });
+    test('parses scroll amount and coordinates', () => {
+        const cli = createCli();
+        const parsed = cli.parse(['node', 'usecomputer', 'scroll', 'down', '500', '--at', '10,20'], { run: false });
+        expect(parsed.args).toMatchInlineSnapshot(`
+      [
+        "down",
+        "500",
+      ]
+    `);
+        expect(parsed.options.at).toBe('10,20');
+    });
+});

package/dist/cli.d.ts

@@ -1,2 +1,6 @@
-export {};
+import type { UseComputerBridge } from './types.js';
+export declare function createCli({ bridge }?: {
+    bridge?: UseComputerBridge;
+}): import("goke").Goke<{}>;
+export declare function runCli(): void;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAuDvE,wBAAgB,SAAS,CAAC,EAAE,MAAuB,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAO,2BAyQzF;AAED,wBAAgB,MAAM,IAAI,IAAI,CAG7B"}