rethocker 0.0.2 → 0.1.1

package/src/actions.ts

@@ -0,0 +1,282 @@
+/**
+ * Built-in macOS action helpers.
+ *
+ * Each function returns a shell command string suitable for use in the
+ * `execute` field of a rule. Pass an array to `execute` to run multiple
+ * actions together.
+ *
+ * @example
+ * import { rethocker, actions } from "rethocker"
+ *
+ * const rk = rethocker([
+ *   { key: "Ctrl+Left",      execute: actions.window.halfLeft() },
+ *   { key: "Ctrl+F",         execute: actions.focusMode.toggle() },
+ *   { key: "Ctrl+Shift+S",   execute: actions.app.focus("Slack") },
+ *   { key: "F8",             execute: actions.media.playPause() },
+ *   // Multiple actions at once:
+ *   { key: "Ctrl+Alt+L",     execute: [actions.app.focus("Slack"), actions.focusMode.on("Work")] },
+ * ])
+ */
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/** Wrap an AppleScript string into a one-liner osascript call. */
+function osascript(script: string): string {
+  // Escape single quotes in the script for shell safety
+  const escaped = script.replace(/'/g, "'\\''");
+  return `osascript -e '${escaped}'`;
+}
+
+/**
+ * Multi-line AppleScript — written to a temp file to avoid shell quoting issues.
+ * Uses a heredoc so the script is passed cleanly regardless of content.
+ */
+function osascriptMultiline(script: string): string {
+  // Use process substitution to avoid temp file cleanup concerns
+  return `osascript << 'RETHOCKER_EOF'\n${script}\nRETHOCKER_EOF`;
+}
+
+// ─── Window layout ────────────────────────────────────────────────────────────
+
+/**
+ * AppleScript that positions a window on screen.
+ * Gets screen bounds dynamically so it works on any display size.
+ * Optionally targets a specific app by name; defaults to the frontmost app.
+ * If the app is not running, it is launched first.
+ */
+function windowScript(
+  posExpr: string, // e.g. "{0, menuBarH}"
+  sizeExpr: string, // e.g. "{screenW / 2, screenH - menuBarH}"
+  appName?: string,
+): string {
+  const activateBlock = appName
+    ? `tell application "${appName}" to activate\ndelay 0.1`
+    : "";
+  const targetBlock = appName
+    ? `tell application "${appName}"
+        set bounds of window 1 to {item 1 of pos, item 2 of pos, (item 1 of pos) + (item 1 of sz), (item 2 of pos) + (item 2 of sz)}
+    end tell`
+    : `tell application "System Events"
+        set frontApp to name of first application process whose frontmost is true
+        tell process frontApp
+            set position of window 1 to pos
+            set size of window 1 to sz
+        end tell
+    end tell`;
+
+  return osascriptMultiline(
+    `
+${activateBlock}
+tell application "Finder"
+    set screenBounds to bounds of window of desktop
+end tell
+set screenW to item 3 of screenBounds
+set screenH to item 4 of screenBounds
+set menuBarH to 30
+set pos to ${posExpr}
+set sz to ${sizeExpr}
+${targetBlock}
+`.trim(),
+  );
+}
+
+export type AppTarget = string | undefined;
+
+export const window = {
+  /** Left half of screen */
+  halfLeft: (app?: AppTarget) =>
+    windowScript("{0, menuBarH}", "{screenW / 2, screenH - menuBarH}", app),
+
+  /** Right half of screen */
+  halfRight: (app?: AppTarget) =>
+    windowScript(
+      "{screenW / 2, menuBarH}",
+      "{screenW / 2, screenH - menuBarH}",
+      app,
+    ),
+
+  /** Top half of screen */
+  halfTop: (app?: AppTarget) =>
+    windowScript("{0, menuBarH}", "{screenW, (screenH - menuBarH) / 2}", app),
+
+  /** Bottom half of screen */
+  halfBottom: (app?: AppTarget) =>
+    windowScript(
+      "{0, menuBarH + (screenH - menuBarH) / 2}",
+      "{screenW, (screenH - menuBarH) / 2}",
+      app,
+    ),
+
+  /** Left third of screen */
+  thirdLeft: (app?: AppTarget) =>
+    windowScript("{0, menuBarH}", "{screenW / 3, screenH - menuBarH}", app),
+
+  /** Center third of screen */
+  thirdCenter: (app?: AppTarget) =>
+    windowScript(
+      "{screenW / 3, menuBarH}",
+      "{screenW / 3, screenH - menuBarH}",
+      app,
+    ),
+
+  /** Right third of screen */
+  thirdRight: (app?: AppTarget) =>
+    windowScript(
+      "{(screenW / 3) * 2, menuBarH}",
+      "{screenW / 3, screenH - menuBarH}",
+      app,
+    ),
+
+  /** Top-left quadrant */
+  quarterTopLeft: (app?: AppTarget) =>
+    windowScript(
+      "{0, menuBarH}",
+      "{screenW / 2, (screenH - menuBarH) / 2}",
+      app,
+    ),
+
+  /** Top-right quadrant */
+  quarterTopRight: (app?: AppTarget) =>
+    windowScript(
+      "{screenW / 2, menuBarH}",
+      "{screenW / 2, (screenH - menuBarH) / 2}",
+      app,
+    ),
+
+  /** Bottom-left quadrant */
+  quarterBottomLeft: (app?: AppTarget) =>
+    windowScript(
+      "{0, menuBarH + (screenH - menuBarH) / 2}",
+      "{screenW / 2, (screenH - menuBarH) / 2}",
+      app,
+    ),
+
+  /** Bottom-right quadrant */
+  quarterBottomRight: (app?: AppTarget) =>
+    windowScript(
+      "{screenW / 2, menuBarH + (screenH - menuBarH) / 2}",
+      "{screenW / 2, (screenH - menuBarH) / 2}",
+      app,
+    ),
+
+  /** Maximize (fill the screen below the menu bar) */
+  maximize: (app?: AppTarget) =>
+    windowScript("{0, menuBarH}", "{screenW, screenH - menuBarH}", app),
+};
+
+// ─── App management ───────────────────────────────────────────────────────────
+
+export const app = {
+  /**
+   * Open the app if not running, then bring it to the foreground.
+   *
+   * @example
+   * execute: actions.app.focus("Slack")
+   * execute: actions.app.focus("com.tinyspeck.slackmacgap") // bundle ID also works
+   */
+  focus: (nameOrBundleID: string): string => {
+    // Bundle IDs contain dots — use `open -b` for them, `open -a` for names
+    const isBundleID = nameOrBundleID.includes(".");
+    return isBundleID
+      ? `open -b '${nameOrBundleID}'`
+      : `open -a '${nameOrBundleID}'`;
+  },
+
+  /**
+   * Quit an app by name or bundle ID.
+   *
+   * @example
+   * execute: actions.app.quit("Slack")
+   */
+  quit: (nameOrBundleID: string): string => {
+    const isBundleID = nameOrBundleID.includes(".");
+    return isBundleID
+      ? osascript(`tell application id "${nameOrBundleID}" to quit`)
+      : osascript(`tell application "${nameOrBundleID}" to quit`);
+  },
+};
+
+// ─── Shortcuts app ────────────────────────────────────────────────────────────
+
+/**
+ * Run a named shortcut from the macOS Shortcuts app.
+ *
+ * @example
+ * execute: actions.shortcut("Morning Routine")
+ */
+export function shortcut(name: string): string {
+  return `shortcuts run '${name}'`;
+}
+
+// ─── Media ────────────────────────────────────────────────────────────────────
+
+export const media = {
+  /** Toggle play / pause in the active media app. */
+  playPause: (): string =>
+    osascript(`tell application "System Events" to key code 100`),
+
+  /** Skip to next track. */
+  next: (): string =>
+    osascript(`tell application "System Events" to key code 101`),
+
+  /** Go to previous track. */
+  previous: (): string =>
+    osascript(`tell application "System Events" to key code 98`),
+
+  /** Toggle system audio mute. */
+  mute: (): string =>
+    osascript(
+      `set volume output muted not (output muted of (get volume settings))`,
+    ),
+
+  /** Set system volume (0–100). */
+  setVolume: (level: number): string =>
+    osascript(`set volume output volume ${Math.max(0, Math.min(100, level))}`),
+
+  /** Increase system volume by a step (default 10). */
+  volumeUp: (step = 10): string =>
+    osascript(
+      `set vol to output volume of (get volume settings)\nset volume output volume (vol + ${step})`,
+    ),
+
+  /** Decrease system volume by a step (default 10). */
+  volumeDown: (step = 10): string =>
+    osascript(
+      `set vol to output volume of (get volume settings)\nset volume output volume (vol - ${step})`,
+    ),
+};
+
+// ─── System ───────────────────────────────────────────────────────────────────
+
+export const system = {
+  /** Put the Mac to sleep immediately. */
+  sleep: (): string => osascript(`tell application "System Events" to sleep`),
+
+  /** Lock the screen. */
+  lockScreen: (): string =>
+    `/System/Library/CoreServices/Menu\\ Extras/User.menu/Contents/Resources/CGSession -suspend`,
+
+  /** Show the desktop (Mission Control: show desktop). */
+  showDesktop: (): string =>
+    osascript(
+      `tell application "System Events" to key code 103 using {command down}`,
+    ),
+
+  /** Open Mission Control. */
+  missionControl: (): string =>
+    osascript(`tell application "Mission Control" to launch`),
+
+  /** Empty the Trash. */
+  emptyTrash: (): string =>
+    osascript(`tell application "Finder" to empty trash`),
+};
+
+// ─── Top-level actions object ─────────────────────────────────────────────────
+
+export const actions = {
+  window,
+  app,
+  shortcut,
+  media,
+  system,
+};

package/src/daemon.ts

@@ -0,0 +1,244 @@
+/**
+ * Daemon — manages the native rethocker-native subprocess lifecycle and IPC.
+ *
+ * Responsibilities:
+ *   - Spawn / stop the native binary
+ *   - Buffer commands sent before ready, flush on startup
+ *   - Parse newline-delimited JSON from stdout and emit typed events
+ *   - Pipe stderr to process.stderr for visibility
+ *
+ * This module knows nothing about rules — it only speaks raw IPC JSON.
+ */
+
+import { EventEmitter } from "node:events";
+import type { DeviceInfo, KeyEvent, RethockerEvents } from "./types.ts";
+
+// ─── Typed EventEmitter (internal, never exported) ────────────────────────────
+
+type Listener = (...args: unknown[]) => void;
+
+export class TypedEmitter extends EventEmitter {
+  override on<K extends keyof RethockerEvents>(
+    event: K,
+    listener: (...args: RethockerEvents[K]) => void,
+  ): this {
+    return super.on(event as string, listener as Listener);
+  }
+  override once<K extends keyof RethockerEvents>(
+    event: K,
+    listener: (...args: RethockerEvents[K]) => void,
+  ): this {
+    return super.once(event as string, listener as Listener);
+  }
+  override off<K extends keyof RethockerEvents>(
+    event: K,
+    listener: (...args: RethockerEvents[K]) => void,
+  ): this {
+    return super.off(event as string, listener as Listener);
+  }
+  override emit<K extends keyof RethockerEvents>(
+    event: K,
+    ...args: RethockerEvents[K]
+  ): boolean {
+    return super.emit(event as string, ...args);
+  }
+}
+
+// ─── Daemon ───────────────────────────────────────────────────────────────────
+
+export interface Daemon {
+  readonly emitter: TypedEmitter;
+  /** Send a raw IPC command. Buffered if the daemon isn't ready yet. */
+  send(obj: Record<string, unknown>): void;
+  /** Start the daemon. Returns the same promise on concurrent calls. */
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  unref(): void;
+  readonly ready: boolean;
+}
+
+export function createDaemon(binaryPath: string): Daemon {
+  const emitter = new TypedEmitter();
+  let proc: Bun.Subprocess<"pipe", "pipe", "pipe"> | null = null;
+  let _ready = false;
+  let buffer = "";
+  let sendQueue: string[] = [];
+  let pendingReady: Array<{ resolve: () => void; reject: (e: Error) => void }> =
+    [];
+  let startPromise: Promise<void> | null = null;
+
+  // ─── Send / queue ─────────────────────────────────────────────────────────
+
+  function send(obj: Record<string, unknown>): void {
+    const line = `${JSON.stringify(obj)}\n`;
+    if (!_ready) {
+      sendQueue.push(line);
+      return;
+    }
+    proc?.stdin.write(line);
+  }
+
+  function flushQueue(): void {
+    for (const line of sendQueue) proc?.stdin.write(line);
+    sendQueue = [];
+  }
+
+  // ─── Message parsing ──────────────────────────────────────────────────────
+
+  function handleMessage(line: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return;
+    }
+    switch (msg.type) {
+      case "ready":
+        _ready = true;
+        flushQueue();
+        for (const p of pendingReady) p.resolve();
+        pendingReady = [];
+        emitter.emit("ready");
+        break;
+      case "keydown":
+      case "keyup":
+      case "flags":
+        emitter.emit("key", msg as unknown as KeyEvent);
+        break;
+      case "matched":
+        if (msg.eventID) {
+          emitter.emit("event", msg.eventID as string, msg.ruleID as string);
+        }
+        break;
+      case "sequence_matched":
+        emitter.emit(
+          "sequence",
+          msg.ruleID as string,
+          msg.eventID as string | undefined,
+        );
+        break;
+      case "devices":
+        emitter.emit("devices", msg.devices as DeviceInfo[]);
+        break;
+      case "error":
+        if (msg.code === "accessibility_denied") {
+          emitter.emit("accessibilityDenied");
+        } else {
+          emitter.emit("error", msg.code as string, msg.message as string);
+        }
+        break;
+    }
+  }
+
+  // ─── Read loops ───────────────────────────────────────────────────────────
+
+  async function readStdout(): Promise<void> {
+    const reader = proc?.stdout.getReader();
+    if (!reader) return;
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.trim()) handleMessage(line);
+        }
+      }
+    } catch {
+      // process exited — handled by the exited promise
+    }
+  }
+
+  async function readStderr(): Promise<void> {
+    const reader = proc?.stderr.getReader();
+    if (!reader) return;
+    const decoder = new TextDecoder();
+    let buf = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.trim()) process.stderr.write(`[rethocker-native] ${line}\n`);
+        }
+      }
+    } catch {
+      // process exited
+    }
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+
+  function start(): Promise<void> {
+    if (startPromise) return startPromise;
+
+    startPromise = new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("rethocker-native startup timed out after 10s"));
+      }, 10_000);
+
+      pendingReady.push({
+        resolve: () => {
+          clearTimeout(timeout);
+          resolve();
+        },
+        reject: (e) => {
+          clearTimeout(timeout);
+          reject(e);
+        },
+      });
+
+      proc = Bun.spawn({
+        cmd: [binaryPath],
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      readStdout();
+      readStderr();
+
+      proc.exited.then((code) => {
+        _ready = false;
+        startPromise = null;
+        emitter.emit("exit", code);
+        const err = new Error(
+          `rethocker-native exited unexpectedly (code ${code})`,
+        );
+        for (const p of pendingReady) p.reject(err);
+        pendingReady = [];
+      });
+    });
+
+    return startPromise;
+  }
+
+  async function stop(): Promise<void> {
+    _ready = false;
+    startPromise = null;
+    proc?.kill();
+    await proc?.exited;
+    proc = null;
+  }
+
+  function unref(): void {
+    proc?.unref();
+  }
+
+  return {
+    emitter,
+    send,
+    start,
+    stop,
+    unref,
+    get ready() {
+      return _ready;
+    },
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import { actions, Key, KeyModifier, rethocker } from "./index.ts";
+
+test("Key constants are strings", () => {
+  expect(Key.capsLock).toBe("capsLock");
+  expect(Key.escape).toBe("escape");
+  expect(Key.brightnessDown).toBe("brightnessDown");
+  expect(Key.volumeUp).toBe("volumeUp");
+  expect(Key.numpadEnter).toBe("numpadEnter");
+});
+
+test("KeyModifier constants are valid modifier strings", () => {
+  expect(KeyModifier.Cmd).toBe("cmd");
+  expect(KeyModifier.Shift).toBe("shift");
+  expect(KeyModifier.Alt).toBe("alt");
+});
+
+test("Key interpolation produces valid key strings", () => {
+  expect(`${Key.capsLock}`).toBe("capsLock");
+  expect(`Cmd+${Key.v}`).toBe("Cmd+v");
+  expect(`${Key.brightnessDown} ${Key.brightnessUp}`).toBe(
+    "brightnessDown brightnessUp",
+  );
+});
+
+test("actions.window returns shell command strings", () => {
+  expect(typeof actions.window.halfLeft()).toBe("string");
+  expect(typeof actions.window.halfRight()).toBe("string");
+  expect(typeof actions.window.maximize()).toBe("string");
+  expect(typeof actions.window.halfLeft("Figma")).toBe("string");
+});
+
+test("actions.app returns shell command strings", () => {
+  expect(typeof actions.app.focus("Slack")).toBe("string");
+  expect(typeof actions.app.focus("com.tinyspeck.slackmacgap")).toBe("string");
+  expect(typeof actions.app.quit("Slack")).toBe("string");
+});
+
+test("actions.media returns shell command strings", () => {
+  expect(typeof actions.media.playPause()).toBe("string");
+  expect(typeof actions.media.mute()).toBe("string");
+  expect(typeof actions.media.setVolume(50)).toBe("string");
+});
+
+test("actions.system returns shell command strings", () => {
+  expect(typeof actions.system.sleep()).toBe("string");
+  expect(typeof actions.system.lockScreen()).toBe("string");
+});
+
+test("rethocker() creates a handle with expected methods", () => {
+  const rk = rethocker();
+  expect(typeof rk.add).toBe("function");
+  expect(typeof rk.remove).toBe("function");
+  expect(typeof rk.enable).toBe("function");
+  expect(typeof rk.disable).toBe("function");
+  expect(typeof rk.on).toBe("function");
+  expect(typeof rk.start).toBe("function");
+  expect(typeof rk.stop).toBe("function");
+  expect(typeof rk.unref).toBe("function");
+  expect(typeof rk.execute).toBe("function");
+  // Stop immediately — don't actually start the daemon in tests
+  rk.stop();
+});

package/src/index.ts

@@ -1 +1,8 @@
-console.log("Hello via Bun!");
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export { actions } from "./actions.ts";
+export { Key, KeyModifier } from "./keys.ts";
+export { rethocker } from "./rethocker.ts";
+export type { RethockerHandle, RethockerRule } from "./rule-types.ts";
+
+export type { KeyEvent, Modifier } from "./types.ts";